Typography

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

Footnotes

Footnotes are useful for small clarifications that should not interrupt the main paragraph flow.¹

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:

• Create the docs structure
• 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.

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.

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.

pnpm add @prosefly/astro-theme-lotus

Python package manager commands are supported too.

pip install astro-lotus-example

uv add astro-lotus-example

poetry add astro-lotus-example

pdm 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.

Tables

Tables are supported for compact reference material.

Long tables should stay readable on narrow screens.

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: H₂O and x².

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.