Writing Content

Create a markdown file in src/content/docs/<section>/<document>.mdx.

It must have the following at the top of the file (also called the frontmatter):

---
title: <your title here>
---

<...your content...>

Don’t forget to add the title field or your page will not work properly.

Markdown Syntax

Since all you’re writing is Markdown you have access to different styles on your text, such as

• headings 1-6 using #, where the heading equals the number of hashes used

Note

Headings 2-3 will automatically be a part of the table of contents at the top right, but headings 1 and 4-6 will not.

• **bold**
• __italic__
• ~~strikethrough~~
• `inline code`
• unordered lists with either * or -
• ordered lists using 1., 2., etc.
  • sublists are created by indenting a line by four spaces
• links

[<link label>](<link URL>)

• images

![<alt text>](<image URL>)

• and code blocks

Use triple backticks (`) before and after your content.
After the first three backticks you can add the language for syntax highlighting.

Starlight

Astro Starlight (the framework used to generate this) also provides other ways to style your docs.

Asides

You can use asides to make content stand out. Surround your content with triple colons (:::). After the first set of colons add note, tip, caution, or danger.

The following will generate a note aside.
:::note
This is a note aside.
:::

Note

This is a note aside.

Tip

This is a tip aside.

Caution

This is a caution aside.

Danger

This is a danger aside.

Custom Titles and Icons

To add a title, add some text between square brackets right after the aside type.

:::tip[Custom Title]
Custom title aside
:::

Custom Title

Custom title aside

There are also built-in icons that Starlight allows you to change the icon used in the aside.

:::danger{icon="close"}
Custom icon
:::

Danger

Custom icon

You can combine these to add a custom title and icon.

:::note[Custom Title]{icon="approve-check"}
Custom title and icon
:::

Custom Title

Custom title and icon

Custom Components

There are built-in components that Starlight ships with. They are straight-forward to use, but remember that your file must be .mdx to use these components. We currently do NOT support Markdoc, so ignore those sections.

If there is something you want to implement, but don’t know how contact the Webmaster.

Submitting Your Document

Once you have created your document open a pull request to the csss-site-docs repo.

References

Astro Starlight markdown reference

Markdown Cheatsheet