Writing Content

Denote uses Markdown for documentation with frontmatter support for metadata.

Frontmatter

Every documentation page starts with frontmatter:

---
title: Page Title
description: A brief description of this page
---

Frontmatter Options

AI Content Tags

Denote's AI features use optional frontmatter fields to improve how AI agents understand and retrieve your documentation:

---
title: Authentication
description: How to authenticate with the API
ai-summary: OAuth2 and API key authentication. Supports JWT tokens, refresh flows, and scoped permissions. Rate limits apply per-key.
ai-keywords:
  - authentication
  - oauth2
  - api-keys
  - jwt
  - security
---

ai-summary — A concise, LLM-optimized summary of the page. Unlike description (which targets humans and SEO), ai-summary should be dense with technical details that help AI agents understand the page's content without reading it. Used in llms.txt, the JSON API, and MCP tool responses.

ai-keywords — A list of keywords for AI retrieval. These are indexed in the search API and MCP search tool, making pages discoverable by semantic concepts that might not appear literally in the content.

Both fields are optional. When ai-summary is absent, Denote falls back to description. When ai-keywords is absent, search relies on content matching.

Markdown Syntax

Headings

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

Headings automatically generate anchor links and appear in the table of contents.

Text Formatting

**Bold text** _Italic text_ `inline code` ~~Strikethrough~~

Bold text renders as strong, italic text as emphasis, inline code with a highlighted background, and strikethrough with a line through it.

Links

[External Link](https://example.com) [Internal Link](/docs/other-page)

Images

![Alt text](/images/screenshot.png)

Images are rendered with lazy loading enabled. Place image files in the static/ directory and reference them with absolute paths.

Lists

Denote supports both flat and nested lists:

- Unordered item 1
- Unordered item 2
  - Nested child item
  - Another nested item
    - Deeply nested
- Back to top level

1. Ordered item 1
2. Ordered item 2
   1. Nested ordered
   2. Another nested
3. Back to top level

Nesting is controlled by indentation — use 2 or more spaces to create sub-lists. You can mix ordered and unordered lists at different levels.

Code Blocks

Use triple backticks with a language hint:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

Supported languages include: typescript, javascript, python, bash, json, yaml, markdown, css, html, rust, go, sql, diff, toml, xml, and more.

Code blocks include a copy button that appears on hover — click the clipboard icon to copy the code content.

Tables

| Feature | Status |
| ------- | ------ |
| Tables  | ✅     |
| Lists   | ✅     |

Tables support left, center, and right alignment using colons in the separator row (:---, :---:, ---:).

Blockquotes

> This is a blockquote. Use it for important notes or quotes.

This is a blockquote. Use it for important notes or quotes.

Horizontal Rules

Use three or more dashes to create a horizontal rule:

---

File Organization

Organize your docs in the content/docs/ directory:

content/docs/
├── introduction.md       # /docs/introduction
├── installation.md       # /docs/installation
├── guides/
│   ├── index.md         # /docs/guides
│   ├── basics.md        # /docs/guides/basics
│   └── advanced.md      # /docs/guides/advanced
└── api/
    └── reference.md     # /docs/api/reference

Extended Markdown Features

Denote uses @deer/gfm which supports GitHub Flavored Markdown extensions.

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another todo

• Completed task
• Incomplete task
• Another todo

GitHub Alerts

GitHub-style alerts using blockquote syntax:

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Footnotes

Here is a sentence with a footnote[^1].

[^1]: This is the footnote content.

Here is a sentence with a footnote¹.

Autolinks

URLs and email addresses are automatically linked:

• https://example.com
• contact@example.com

Best Practices

1. Use descriptive titles — help users understand what the page covers
2. Add descriptions — improve SEO and search results
3. Link related pages — help users discover more content
4. Use code examples — show, don't just tell
5. Keep pages focused — one topic per page
6. Use nested lists — organize complex information hierarchically

Next Steps

• Components — Built-in UI components and islands
• Configuration — Customize your site settings
• Theming & Styling — Colors, dark mode, and CSS variables