---
title: Markdown Authoring Guide
section: docs
summary: Conventions for writing notes, front matter fields, and embedding code or media in the site.
tags: [markdown, style, notes]
nav: 1
---

# Markdown Authoring Guide

## Front matter
Provide metadata at the top of every note:

```
---
title: Example Title
section: docs
summary: One-sentence overview for listings.
tags: [topic, keyword]
nav: 1
---
```

- `section`: logical bucket (docs, infra, backend, frontend, etc.).
- `nav`: optional integer to influence ordering within a section; lower numbers show first.

## Writing tips
- Start with an `#` heading matching the title.
- Keep paragraphs short; use bullet lists for tasks.
- Use fenced code blocks with language hints (` ```bash `, ` ```js `) for highlighting.
- Link to related notes with absolute paths, e.g., `/docs/markdown-authoring-guide/`.

## Media
Place images next to the note or in an `/assets/media` folder and reference relatively.

## Testing locally
Run `npm run build` to regenerate HTML. Open `dist/index.html` in a browser to review layout and syntax highlighting.