RIOT/doc/guides/misc/how_to_doc.md

---
title: Creating Guides & How Starlight Works
description: Explanation on how the starlight "build system works and how to create guides
code_folder: examples/basic/hello-world/
---

## What is Starlight?

[Starlight](https://starlight.astro.build/) is a documentation site generator built on top of [Astro](https://astro.build/), a popular modern web framework, by the Astro team itself.
Starlight is designed to be fast, flexible, and easy to use, making it a great choice for creating documentation sites. It supports Markdown and MDX, allowing you to write content in a familiar format while also enabling extensive access to the entire modern web ecosystem if needed.

For RIOT Starlight is meant to exclusively host guides while the API documentation is generated by Doxygen and hosted on the [RIOT API documentation](https://doc.riot-os.org/) site.
Where Doxygen has a very automated approach to generating documentation, Starlight is meant to be more flexible and allow for a more human touch that is needed for tutorials and guides,
which means that we both have the control over the content and layout but at the same time have to put more active effort into the UX of the documentation itself. At the same time writing guides in Markdown allows us to keep the guides readable in the repository itself, which is a big plus.

## How to run the Site locally

To run the site locally, you need to have [Node.js](https://nodejs.org/) installed.
It is highly recommended to use a version manager such as [NVM](https://github.com/nvm-sh/nvm) to manage your Node.js versions.

Please make sure to use a fairly recent version of Node.js, some distributions (such as Ubuntu) ship with a very old version of Node.js that is not compatible with Starlight.
Generally, the latest LTS version should work fine (As of writing v22), as specified in the [Astro documentation](https://docs.astro.build/en/install-and-setup/#prerequisites).

Once installed you should be able to install the dependencies and run the site locally with the following command, making sure to be within the root of the repository:

```bash title="Running the site locally (within the root of the repository)"
make doc-starlight
```

This will start a local development server and open the site in your default web browser. The resulting output should look like this:

```bash title="Output of running the site locally"
(3.12.8) [user@computer RIOT]$ make doc-starlight
Installing starlight...

Starlight installed successfully.
Starting starlight live server...

> guide@0.0.1 dev
> astro dev

13:32:10 [types] Generated 0ms
13:32:10 [content] Syncing content
13:32:10 [content] Synced content

 astro  v5.6.1 ready in 1490 ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

13:32:10 watching for file changes...
```

You can then browse the site at the URL shown in the output, which is usually `http://localhost:4321/`.

One big advantage of Starlight is that it supports hot reloading, which means that any changes you make to the content will be reflected in the browser immediately without needing to refresh the page. This makes it easy to see how your changes affect the site in real-time.

You can also use the `make build` command within the `doc/starlight` folder to build the site for production. This will create a static version of the site in the `dist` directory, which can be deployed to any static file hosting service.

```bash title="Building the site for production"
cd doc/starlight && make build
```

### Folder Structure

Generally, there are two folders that are important for the guides:

- `doc/guides/`: This folder contains the actual guides. Each guide is a Markdown file with a specific structure that Starlight uses to generate the navigation and other metadata for the guide.
- `doc/starlight/`: This folder contains the Starlight configuration files. The most important file is `astro.config.mjs`, which contains the configuration for the site, including the navigation structure and other settings.

We will go into more detail about how to create a new guide in the next section, but for now, it is important to understand that the guides are located in the `doc/guides/` folder and the configuration files are located in the `doc/starlight/` folder.

## How to Create a new Guide

Now that we understand how to run the site locally, let's look at how to create a new guide.
The first step is to create a Markdown file within `doc/guides/` with the following structure:

```markdown title="doc/guides/test/hello_world.md"
---
title: My New Guide
description: This is a description of my new guide
---

Hello World!
```

Starlight uses the frontmatter of the Markdown file to generate the navigation and other metadata for the guide. On Github this will appear as a small table at the top of the file so your guide will still be readable in the repository.

Now you can add content to the guide using Markdown. Starlight supports all the standard Markdown features, including headings, lists, links, images, and code blocks. You can also use MDX to embed JavaScript, Components, and other features directly into your Markdown files. This allows you to create interactive components and dynamic content within your guides.

You can see a full list of the supported features in the [Starlight documentation](https://starlight.astro.build/guides/authoring-content/).

### MDX

MDX is a superset of Markdown that allows you to use JSX components within your Markdown file. This means that you can do things such as importing reusable components. One component that is/should be used frequently is the `Contact` component, which adds a small little note explaining some ways of getting help from the RIOT community. This component is imported like this:

```mdx title="doc/guides/test/hello_world.mdx"
import Contact from '@components/contact.astro';

<Contact/>
```

:::danger[Keep it simple]
Please always keep in mind that the more non-standard Markdown you write, the more it will worsen the readability of the guide in the repository itself.

If you are targeting an experienced audience, a lot of them will be reading the guides locally within their IDE and not in a browser.
:::

### Placing the Guide

One last manual step is to add the new guide to the navigation. This is done in the `doc/starlight/astro.config.mjs` file.

Compared to the Doxygen output we want to be extremely careful about the navigation and only show the guides that are relevant to the user and in a logical order that does not overwhelm the user with too many options at once.

It is also important to note that the place in each section is directly related to the order in which the guides are listed in the `sidebar` array in the `astro.config.mjs` file. The order of the items in the array determines the order in which they will be displayed in the navigation. So if you want to place your guide at the top of a section, you should add it to the beginning of the `items` array for that section.

Generally, the less information you declare within the config the better, given that ideally your frontmatter information is enough to generate the navigation.

You can either add your guide to an existing section or create a new section. In the event that you want to simply append your guide to an existing section, you can simply add the file name to the list of files in the section. The root of the so called `slug` of your file is the guides folder itself, so a guide under `doc/guides/test/hello_world.md` will have the slug `test/hello_world.md`.

:::note
There is one exception to this rule, if your file is called index.md, the slug will be the name of the folder it is in. For example `doc/guides/test/index.md` will have the slug `test`.
:::

### Creating a new Section

Generally, we want to avoid creating new sections unless absolutely necessary. For example, if you create a totally new tutorial that spans multiple files, it might make sense to create a new section.
In this case, you can create a new section by adding a new entry to the `sidebar` array in the `astro.config.mjs` file. The entry should look like this:

```javascript title="doc/starlight/astro.config.mjs"
sidebar: [
    {
        label: "The Best Tutorial",
        items: [
            "tutorial/best_tutorial",
        ],
    },
],
```

:::tip
Sections can also be nested, so you can create a section within a section by adding another array to the `items` array. This is useful for organizing your guides into sub-sections.
:::

### Code Block Testing

If you are writing a guide that includes code blocks it is important to test them to make sure they work as expected.
To facilitate this, we have a small script that runs over the code blocks in the guide and compares them to a specified example folder.

You can also utilize this script to test your code blocks locally before pushing them to the repository. To do this, you need to run the following command:

```bash title="Running the code block testing script"
./dist/tools/code_in_guides_check/check_for_code.sh
```

For example, let's say that we have a tutorial that explains the hello world example.
This example is located in `examples/basic/hello-world/` and the guide is located in `doc/guides/test/hello_world.md`.

First we have to tell the script where to find the example folder. This is done by adding the `code_folder` key to the frontmatter of the guide. The value should be the path to the example folder relative to the root of the repository.

```markdown title="Example guide with code_folder"
---
title: Tutorial Hello World
description: This is a description of my new guide
code_folder: examples/basic/hello-world/
---
```

Then we can add the code blocks to the guide. The script will automatically detect the code blocks and run them against the example folder.


````markdown  title="This code block will be tested against the hello world example"
```c
int main(void)
{
    puts("Hello World!");
```
````

In the case that you want to skip the code block testing, you can add the `<!--skip ci-->` comment one line above the code block. The script will ignore this code block and not run it against the example folder.

````markdown title="This code block will be ignored by the script"
<!--skip ci-->
```c
int not_main(void)
{
    puts("Goodbye World!");
```
````

:::note
The script will only run the code blocks that are in C, it will ignore any other code blocks written in other languages.
:::