Write a documentation page

Use Markdown for ordinary pages. Reserve MDX and custom components for a clear need; most guides require only text, images, tables, and code blocks.

Give the page stable metadata

Start each page with frontmatter:

---
title: Describe one useful task
description: A short explanation of what this page helps the reader do.
slug: docs/guides/your-topic
sidebar:
  label: A short navigation label
  order: 5
---

Starlight renders the title as the page’s main heading. Start content headings at ##. Plugin folders are listed automatically; for a new core guide, add its slug to the appropriate sidebar group in astro.config.mjs.

Keep application help links working

A page’s slug is its public address. Keep it stable even when you rename the source file. A help link can target a heading, for example:

https://filmopen.ai/docs/guides/create-project/#create-the-project

Changing a heading can change its automatic anchor. Preserve an old anchor with an explicit HTML marker immediately before the renamed heading:

<span id="previous-heading"></span>

When a page must move, add its old URL and the new destination to public/_redirects. Redirects are for page paths; preserve old fragment IDs in the destination page because a server never receives the URL fragment.

Include screenshots

Place screenshots under src/assets/docs/, preferably in a folder for the guide or plugin. Use a relative Markdown image path, with the correct number of parent directories from your page:

![The new project dialog with a short name and author handle entered](../../../../assets/docs/create-project/new-project.png)

Astro processes local Markdown images during the build. Prefer PNG for text-heavy UI captures and WebP or JPEG for photographic content. Crop to the relevant application area, keep text legible, and give every image meaningful alternative text. Never use a generated mockup to represent actual application behavior.

Format examples

Use a language identifier after the opening code fence for syntax highlighting. A title can identify the example file:

```json title="filmopen-project.json"
{
  "filmopen": 1,
  "tag": "cartographer"
}
```

Use Markdown links with public routes, such as [Create a project](/docs/guides/create-project/), instead of filesystem paths.

Tables work well for comparing fields or choices:

| Field | Meaning |
| --- | --- |
| `tag` | The project's short name. |

Add a useful note

:::note[Current application]
This behavior describes milestone 3. A later revision may differ.
:::

Use notes sparingly. State limitations where they affect the task rather than burying them at the end.

Review before submitting

Run npm run verify. This checks types, reference integrity, the production build, internal links, heading anchors, images, and redirects. Search is generated during the production build; use npm run preview to try the complete static search experience.