Markdown Syntax

Lotus uses Astro content collections and MDX, so standard Markdown remains the default authoring format for most docs pages.

Headings

Use headings to create page structure and table-of-contents anchors.

## Section title
### Subsection title
#### Detail title

Add a custom heading ID when a translated or edited heading needs a stable URL hash.

## Manual setup {#manual-setup}

Lotus removes the marker from the rendered heading, uses manual-setup for the heading id, and keeps table-of-contents links in sync.

Do not add a top-level # Heading at the start of the MDX body. Lotus renders the page title from frontmatter in the layout.

Paragraphs

Separate paragraphs with a blank line.

This is the first paragraph.

This is the second paragraph.

Line breaks inside a paragraph are collapsed by default. Use a blank line when you want a new paragraph.

Emphasis

Use emphasis for inline stress and strong emphasis for important terms.

This sentence has *emphasis* and **strong emphasis**.

You can also combine ***strong emphasis with emphasis***.

Links

Use inline links for most references.

Read the [Astro documentation](https://docs.astro.build/).

Reference-style links are useful when the same URL appears repeatedly.

Read the [Astro documentation][astro-docs].

[astro-docs]: https://docs.astro.build/

Images

Images use the same bracket syntax as links, with a leading !.

![Lotus screenshot](/images/lotus-screenshot.png)

Use meaningful alt text. If the image is decorative, keep the alt text empty. See Images for galleries, figures, captions, raw img, and iframe embeds.

Lists

Unordered lists use -, *, or +. Lotus examples prefer -.

- Install the package.
- Configure the integration.
- Add documentation content.

Ordered lists use numbers.

1. Install dependencies.
2. Configure Astro.
3. Start the dev server.

Nested lists are indented by two or four spaces.

- Configuration
  - Site
  - Appearance
  - Navbar

Task Lists

Task lists are supported through GitHub Flavored Markdown.

- [x] Create the docs structure
- [ ] Publish the package

Blockquotes

Use blockquotes for quoted material or important contextual notes.

> Lotus is designed for documentation that should feel compact, readable, and
> easy to scan.

Inline Code

Use backticks for inline code, commands, file names, and identifiers.

Run `pnpm dev` and edit `src/theme.config.ts`.

Code Blocks

Use fenced code blocks for longer snippets. Add a language name when possible.

```ts
export const enabled = true;
```

Lotus uses Expressive Code for fenced code blocks by default. See Code Blocks for titles, highlighted lines, copy buttons, package-manager tabs, and configuration.

Tables

Tables are supported for compact reference material.

| Option | Purpose |
| --- | --- |
| `docsBase` | Docs route prefix |
| `navbar` | Main navigation items |

Horizontal Rules

Use a horizontal rule to separate large sections.

---

Escaping Characters

Use a backslash when Markdown punctuation should render literally.

\*This text is not emphasized.\*

Raw HTML And MDX

MDX allows HTML elements and imported Astro components in the same file.

<kbd>Ctrl</kbd> + <kbd>K</kbd>

Prefer Markdown syntax for prose and MDX components for reusable UI patterns.