The hallmark of every great project is equally great documentation, but it can be increasingly difficult for developers to keep both in sync. Luckily, I’ve been experimenting again with a combination of Starlight and MarkdownSnippets to make maintaining code samples and documentation much more convenient.

In this post, we’ll see how to set up your repository so that MarkdownSnippets pulls samples from your codebase and updates your Starlight documentation.

Directory Structure and Tools

To get started, let’s set up our repository for success. Let’s begin with folders. We’ll want to create the following folders at the root of a newly created directory.

- docs
- src

The docs directory will hold our documentation powered by Starlight, and the src directory will have all our .NET code.

We’ll want to run the following dotnet commands within the same directory.

dotnet new tool-manifest

Next, let’s install the MarkdownSnippets tool.

dotnet tool install MarkdownSnippets.Tool

Finally, let’s create the MarkdownSnippets configuration file of mdsnippets.json, which will tune our snippet generation to work with Starlight.

{
  "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/refs/heads/main/schema.json",
  "Convention": "InPlaceOverwrite",
  "WriteHeader": false,
  "ReadOnly": false,
  "LinkFormat": "None",
  "OmitSnippetLinks": true
}

Following the steps correctly, you’ll have the following files and folders.

- docs
- src
- .config
- mdsnippets.json

Great! Let’s write some .NET code in our src directory now.

Our .NET Code Samples

Change to the src directory and create a new Console application. Any will do. What’s important is using the MarkdownSnippets convention to develop a block of code to be extracted. Here’s the one I’m using in Program.cs.

// begin-snippet: App:HelloWorld
// Program.cs
Console.WriteLine("Hello, Again!");
// end-snippet

That’s it! Write and decorate as many code samples as you’ll use in the next section.

Our Starlight Documentation

Now, let’s move into the docs directory and run the following command. Note you’ll need both Node and Yarn installed.

yarn create astro --template starlight

From here, follow the Astro wizard to create a new documentation site. From the root, your directory structure should look similar to the following.

- docs
	- .astro
	- .vscode
	- .yarn
	- src
	- public
	- astro.config.mjs
	- package.json
	- ...
- src
	- App
		- bin
		- obj
		- App.csproj
		- Program.cs
- mdsnippets.json

Now, let’s update our package.json to scan our C# project, find snippets, and update our documentation.

{
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "mdsnippets": "cd .. && dotnet mdsnippets",
    "dev": "npm run mdsnippets && astro dev",
    "start": "npm run dev",
    "build": "npm run mdsnippets && astro build"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.29.3",
    "astro": "^4.16.10",
    "sharp": "^0.32.5"
  }
}

Feel free to add or remove any additional scripts or dependencies for your particular use case. This is the bare minimum for this post.

Now, let’s write some documentation. Find the example.md file under docs/src/content/docs/guides/ and write the following markdown.

---
title: Hello, World!
description: Creating your first .NET Console Application
---

## Getting Started

Your first .NET application will be a console application, or what the cool folks like to call it, an app. Create a new project using the
`dotnet` CLI command `new`.

```bash title="Terminal"
dotnet new console -o HelloWorld && cd ./HelloWorld
```

Then, add the following code in the `Program.cs` file.

snippet: App:HelloWorld

Then run the app by using the following command.

```bash title="Terminal"
dotnet run
```

Congratulations!

Now, run the dev command from the root directory. MarkdownSnippets will transform the snippet: App:HelloWorld in your Markdown to the following.

---
title: Hello, World!
description: Creating your first .NET Console Application
---

## Getting Started

Your first .NET application will be a console application, or what the cool folks like to call it, an app. Create a new project using the
`dotnet` CLI command `new`.

```bash title="Terminal"
dotnet new console -o HelloWorld && cd ./HelloWorld
```

Then, add the following code in the `Program.cs` file.

<!-- snippet: App:HelloWorld -->

```cs
// Program.cs
Console.WriteLine("Hello, Again!");
```

<!-- endSnippet -->

Then run the app by using the following command.

```bash title="Terminal"
dotnet run
```

Congratulations!

You can change the code in Program.cs and rerun the command to see the documentation update.

Conclusion

If you’re working on code-heavy documentation where samples speak louder than words, then combining MarkdownSnippets with Starlight is a great pairing. You’ll want to develop a good naming convention to make finding and altering samples easier, after which you’ll be sure that any code samples are valid, compiled, and run. After all, as developers, we all want to get it right the first time.

As always, thanks for reading, and cheers.