39 lines
1.0 KiB
Markdown
39 lines
1.0 KiB
Markdown
---
|
|
title: Markdown Authoring Guide
|
|
section: dev-notes
|
|
summary: Conventions for writing notes, front matter fields, and embedding code or media in the site
|
|
tags: [markdown, style, notes]
|
|
nav: 2
|
|
---
|
|
|
|
## Front matter
|
|
|
|
Provide metadata at the top of every note:
|
|
|
|
```markdown
|
|
---
|
|
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
|
|
|
|
- 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.
|