# Writing pages

> Add Markdown pages, wire them into the sidebar, and link between them.

Page: https://schubergphilis.github.io/ai-training/guides/writing-pages/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

Pages are Markdown (`.md`) or MDX (`.mdx`) files under
`site/src/content/docs/`. The path under that directory becomes the URL, and
each page needs at least a `title` in its frontmatter.

## Add a page

Create `site/src/content/docs/guides/my-page.md`:

```markdown
---
title: My page
description: A short summary used for SEO and social cards.
---

Your content here.
```

That page is served at `/guides/my-page/` (under the deploy base path).

## Wire it into the sidebar

The sidebar is defined explicitly in `site/astro.config.mjs`. Add your page to
a group's `items`:

```js
{
	label: 'Authoring',
	items: [
		{ slug: 'guides/writing-pages', label: 'Writing pages' },
		{ slug: 'guides/my-page', label: 'My page' },
	],
},
```

## Links and images

Write internal links and image sources **root-relative**
(`/guides/my-page/`, `/diagram.png`) rather than with the deploy base path.
A small rehype plugin in `astro.config.mjs` prepends the base path
(`/ai-training`) at render time. This lets the same Markdown work in
local dev and on GitHub Pages.

```markdown
See the [contributing page](/contributing/).

![A diagram](/diagram.png)
```

The one exception is the landing page's hero action links and any raw HTML
`<a>` tags, which are used verbatim and must include the base path.

## The landing page

`index.mdx` uses Starlight's `splash` template to render a hero and card grid
instead of the usual docs layout. It is a separate landing page - not the first
sidebar entry - so the sidebar starts with your actual content.