Writing notes

Create a page

Add a Markdown file to src/content/docs/. Use .mdx when you want to include an Astro component, such as a callout.

For example, src/content/docs/Linux/storage.mdx becomes /docs/linux/storage/.

Add the metadata

Every page needs a title and description. The remaining fields control its position in the sidebar.

---
title: "Storage"
description: "Notes on persistent storage in the home lab."
order: 2
draft: false
---

• Folders create sidebar sections automatically: Docker, Linux, and Networking.
• Add .md or .mdx files inside a folder to create pages in that section.
• Sections are sorted alphabetically. No section metadata is needed.
• order sorts pages within a group. Lower numbers appear first.
• sidebarHidden: true hides a page from the sidebar while keeping its URL accessible.
• draft: true keeps a page out of the built site, sidebar, and search index.

Structure the note

The page title is already the main heading. Start the body with ## headings, and use ### for subsections. Both appear in the page outline automatically.

A useful structure is:

1. Context — What problem does this note solve?
2. Steps — What did you do, and in what order?
3. Verification — How do you know it worked?
4. References — Where can you find more detail?

Use a callout

Import the component after the metadata in an .mdx file:

import Callout from "@/components/Callout.astro";

<Callout type="info">
  Keep the context close to the instructions.
</Callout>

Preview a change

Run the development server from the project directory:

npm run dev

Open the local address shown in the terminal and visit /docs/. Before publishing, check the production build:

npm run build

New pages appear in the sidebar automatically. Search is generated during the production build.