# Markdown Syntax

Reference the core Markdown patterns supported inside Lotus docs.

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.

```md
## Section title
### Subsection title
#### Detail title
```

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

```md
## 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.

```md
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.

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

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

## Links

Use inline links for most references.

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

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

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

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

## Images

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

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

Use meaningful alt text. If the image is decorative, keep the alt text empty.
See [Images](/docs/essentials/images/) for galleries, figures, captions, raw
`img`, and iframe embeds.

## Lists

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

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

Ordered lists use numbers.

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

Nested lists are indented by two or four spaces.

```md
- Configuration
  - Site
  - Appearance
  - Navbar
```

## Task Lists

Task lists are supported through GitHub Flavored Markdown.

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

## Blockquotes

Use blockquotes for quoted material or important contextual notes.

```md
> 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.

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

## Code Blocks

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

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

Lotus uses Expressive Code for fenced code blocks by default. See
[Code Blocks](/docs/essentials/code-blocks/) for titles, highlighted lines,
copy buttons, package-manager tabs, and configuration.

## Tables

Tables are supported for compact reference material.

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

## Horizontal Rules

Use a horizontal rule to separate large sections.

```md
---
```

## Escaping Characters

Use a backslash when Markdown punctuation should render literally.

```md
\*This text is not emphasized.\*
```

## Raw HTML And MDX

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

```mdx
<kbd>Ctrl</kbd> + <kbd>K</kbd>
```

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