Writing a page

The first part of creating a new page is to create a new file in the src/content/docs directory. The file should be named with a .md or .mdx extension, depending on whether you want to use Markdown or MDX syntax.

For example, if you want a simple page without using any external components, you can create a .md file. Otherwise, if you want to use components like <FileTree>, you can create a .mdx file.

Once you have created the file, you can start writing your content. The first part of the file should be a frontmatter block, which is a YAML block that contains metadata about the page. This includes the title, description, and any other relevant information.

src/content/docs/guides/writing-a-page.mdx

---
title: Writing a page
description: How to create and write a page.
---

This tells Starlight what the title and description of the page are, which will be used in the sidebar.

After which you can write the actual page contents using Markdown or MDX syntax. For example, you can use headings, paragraphs, lists, and other Markdown features to structure your content.

An example could look like this:

#### Writing a page
This is an example of a page written in Markdown. You can use headings, paragraphs, lists, and other Markdown features to structure your content.

You can also use MDX components to enhance your page. For example, you can use the `<FileTree>` component to show a file tree of your project:

import { FileTree, Code } from '@astrojs/starlight/components'

<FileTree>
- src
    - content
        - docs
            - guides
                - writing-a-page.mdx
</FileTree>

Then for code you can use the markdown syntax like so:

\`\`\`js
console.log('Hello, world!');
\`\`\`

or for diffs

\`\`\`diff
- This is a line that will be removed.
+ This is a line that will be added.
\`\`\`

which would render as:

---

Writing a page

This is an example of a page written in Markdown. You can use headings, paragraphs, lists, and other Markdown features to structure your content.

You can also use MDX components to enhance your page. For example, you can use the <FileTree> component to show a file tree of your project:

• Directorysrc

  • Directorycontent

    • Directorydocs

      • Directoryguides

        • writing-a-page.mdx

Then for code you can use the markdown syntax like so:

console.log('Hello, world!');

or for diffs

This is a line that will be removed.
This is a line that will be added.

---

There are other components and markdown syntax rules you can utilize, just check out the Starlight documentation for more information on how to use them.

The theme we are using also has example pages that you can reference at the docs/src/content/docs folder in the repository.