# Typography
Review the default prose scale, spacing, and markdown element styles.
This page collects supported Markdown patterns in one place so typography
changes can be reviewed without jumping between feature pages. It intentionally
uses mostly plain content elements rather than custom layout components.
Lotus prose is tuned for documentation pages with side navigation and a table
of contents. Body text should feel readable beside dense navigation, while
headings should mark sections without becoming page-level display type.
## Headings
The page title above is rendered from frontmatter as the document `h1`. Content
headings start at `h2` so the table of contents and page outline stay stable.
### Heading Level Three
Subsections are smaller than section headings but still need enough weight for
long technical pages. Use them for focused topics, configuration groups, or
steps inside a larger section.
#### Heading Level Four
Small headings are useful inside dense references, especially before short
paragraphs or lists.
##### Heading Level Five
Fifth-level headings should stay compact and should not break the reading flow.
###### Heading Level Six
Sixth-level headings are available for rare deep reference pages.
## Paragraphs And Line Breaks
Paragraphs are separated by a blank line. The spacing between paragraphs should
be clear enough for scanning but compact enough that a medium-length guide still
feels continuous.
This paragraph contains a hard line break after the first sentence.\
The second line should stay visually connected to the first line.
## Emphasis
Use **strong text** when a term needs emphasis. Use _italic text_ sparingly for
phrasing, citations, or quoted labels. You can combine both as
**_strong italic text_** when the content really needs that treatment.
GitHub Flavored Markdown also supports ~~strikethrough text~~ for removed or
obsolete values.
## Links
Inline links such as [the installation guide](/docs/installation/) should
remain visible without pulling too much attention away from the sentence.
Reference-style links are useful when the same URL appears repeatedly. This
sentence links to the [Astro documentation][astro-docs].
[astro-docs]: https://docs.astro.build/
## Footnotes
Footnotes are useful for small clarifications that should not interrupt the
main paragraph flow.[^theme-note]
[^theme-note]: This footnote checks the spacing and link-back style generated by
the Markdown renderer.
## Inline Code
Inline code like `docsBase`, `themeConfig.sidebars`, `src/theme.config.ts`, and
`--lotus-text-muted` should sit comfortably inside a line of prose without
changing the paragraph rhythm.
## Lists
Use unordered lists for related notes or capabilities:
- Configure project metadata, favicon, footer links, and appearance tokens.
- Author pages with MDX and the default documentation layout.
- Override selected theme components when a project needs custom behavior.
Use ordered lists for procedural content:
1. Install the theme package and Astro integration.
2. Add documentation content under the configured docs collection.
3. Start the dev server and review the generated navigation.
Nested lists should stay compact:
- Appearance
- Accent color
- Gray scale
- Radius
- Navigation
- Navbar links
- Sidebar groups
- Footer sections
Task lists are supported through GitHub Flavored Markdown:
- [x] Create the docs structure
- [x] Configure MDX and Expressive Code
- [ ] Publish the package
## Blockquote
> Documentation typography should make structure obvious without forcing every
> section to become a visual component.
Blockquotes can contain more than one paragraph.
> The first paragraph introduces the quoted idea.
>
> The second paragraph should keep the same muted tone and left rule.
## Code Blocks
Fenced code blocks render with Expressive Code by default.
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import lotus from '@prosefly/astro-theme-lotus';
import themeConfig from './src/theme.config';
export default defineConfig({
integrations: [lotus(themeConfig)],
});
```
Plain text blocks are also supported.
```txt
src/content/docs/
overview.mdx
configuration/
appearance.mdx
```
## Package Manager Commands
Shell blocks that contain package-manager install commands can be converted to
package-manager tabs by the Lotus markdown integration.
```sh
pnpm add @prosefly/astro-theme-lotus
```
Python package manager commands are supported too.
```sh
uv add astro-lotus-example
```
## Images
Images should keep their aspect ratio, fit the content column, and inherit the
prose radius.
Captions should use muted text and compact spacing.
Unsplash images make the typography page useful for reviewing media spacing,
border radius, captions, and dark-mode contrast.
## Tables
Tables are supported for compact reference material.
| Element | Purpose | Visual target |
| --- | --- | --- |
| Paragraph | Main reading text | Comfortable line height and steady rhythm |
| Heading 2 | Major content section | Compact but easy to scan |
| Heading 3 | Subsection | Clear hierarchy without oversized type |
| Inline code | Token or API name | Visible, but not visually heavy |
| Table | Reference data | Dense enough for repeated scanning |
Long tables should stay readable on narrow screens.
| Option | Default | Description |
| --- | --- | --- |
| `appearance.accent` | `'indigo'` | Sets the main accent color used by links, active navigation, and focused controls. |
| `appearance.gray` | `'neutral'` | Selects the neutral gray scale used by text, borders, surfaces, and muted UI. |
| `appearance.radius` | `'medium'` | Controls the global corner style while allowing fixed components to cap extreme values. |
## Horizontal Rule
Content above the rule should feel related to the page. Content below the rule
should read as a separate closing block.
---
Final paragraphs can be used to check the visual relationship between body copy,
rules, and following content.
## Escaped Characters
Escaped Markdown punctuation should render literally:
\*This text is not emphasized.\*
\`This text is not inline code.\`
## Raw HTML And MDX
MDX allows HTML elements inside Markdown content. Keyboard labels such as
Ctrl + K should align with surrounding text.
Inline HTML like highlighted text, API,
and small text should inherit the surrounding prose rhythm.
Inserted text can use underlined additions, while deleted text can
use removed phrases.
Math and technical notation can use subscript and superscript inline:
H2O and x2.
Program output can use 200 OK, variables can use request,
short quotes can use semantic tokens keep components stable, and citations
can use Lotus Design Notes.
