Writing Docs in Markdown

This page is itself a Markdown file at content/docs/guides/markdown-authoring.mdx. Adding a doc no longer means writing a React component and editing the sidebar and search index by hand — just create a file here and it shows up everywhere.

How it works

Drop a .md or .mdx file under content/docs/. The file path becomes the URL:

File	URL
`content/docs/security/tools/netcat.mdx`	`/docs/security/tools/netcat`
`content/docs/guides/index.mdx`	`/docs/guides`

The page, its sidebar entry, and its search-index entry are all generated from the file and its frontmatter automatically.

Frontmatter

Every doc starts with a YAML block:

yaml

---
title: Netcat (nc)              # required
description: The TCP/IP Swiss Army knife
category: Security              # sidebar group; defaults to the first path segment
tags: [Networking, Utility]
icon: Terminal                 # a lucide icon name (see icon-map.tsx)
iconColor: text-green-600 dark:text-green-400
order: 10                       # sort order within the sidebar group
---

Only title is required.

Writing content

Plain Markdown works — headings, bold, lists, tables, and code fences:

bash

nc -lvnp 4444          # listen on port 4444
nc target.com 80       # connect to a host

Callouts

Use blockquote shorthand for callouts:

Tip

Plain Markdown is enough for most pages — reach for components only when you need them.

Warning

The first path segment becomes the sidebar group unless you set category.

Available kinds: [!INFO], [!TIP], [!WARNING], [!DANGER], [!EXAMPLE].

Components (optional)

Because these are MDX files, you can also drop components straight into the page when Markdown isn't enough:

Good to know

Anything exported from the MDX mapping can be used inline like this.

Editing an existing page

Open its file under content/docs/, change the text, save. The dev server hot-reloads; a push to main deploys it. That's the whole loop.