Standard Markdown

---

Phosphor supports all standard Markdown syntax you already know. Every page is a .md file in your pages/ directory.

Headings

Use ## for sections and ### for subsections. Phosphor uses these to generate the sidebar table of contents and the search index.

• ## Section — creates a styled section with accent rule, auto-generates an ID for anchor links
• ### Subsection — creates a subsection heading with auto-generated ID
• #### Minor heading — smaller heading for subdivisions within a subsection

Text Formatting

Standard inline formatting works as expected:

• **bold text** renders as bold text
• *italic text* renders as italic text
• `inline code` renders as inline code

Links

Standard Markdown links work for both internal and external targets:

• [Link Text](https://example.com) — external link
• [Other Page](other-page.html#section) — internal link (use .html extension, not .md)

Images

![Alt text](path/to/image.png)

Place images in your pages/ directory or reference external URLs.

Lists

Unordered lists use - or *:

• First item
• Second item
• Third item with inline code

Ordered lists use numbers:

1. Step one
2. Step two
3. Step three

Code Blocks

Standard fenced code blocks render with the Phosphor monospace styling:

function hello() {
  console.log("Hello from Phosphor");
}

Tables

Standard Markdown tables render with the Phosphor table styling:

Horizontal Rules

Use --- on its own line to create a horizontal divider:

---

The divider above was created with three dashes.

Components

---

Phosphor extends Markdown with rich components using the ::: fenced block syntax. These render as styled HTML elements that match the Terminal Noir theme.

Callouts

Callouts highlight important information. Three types are available:

Callout Syntax

:::tip Your Title Here
The body text goes on subsequent lines.
You can use **bold**, *italic*, and `code` in the body.
:::

The type can be tip (teal), info (blue), or warn (amber). The first word after ::: is the type, everything after it on that line is the title.

Terminal Blocks

Terminal blocks render as realistic terminal windows with colored dots, a title bar, and syntax-colored output. Lines starting with $ are commands, lines starting with # are comments, and everything else is output.

Terminal Syntax

Use a fenced code block with the terminal language identifier:

```terminal
$ command-here
Output appears as dimmed text
# This is a comment
$ another-command --with-flags
```

Line types:

Cards

Cards display features, concepts, or options in a responsive grid. Each card has an icon, color accent, title, and description.

Card Syntax

:::cards
::card{icon="icon-name" color="teal" title="Card Title"}
Description text. Supports **bold** and `code`.
::

::card{icon="another-icon" color="amber" title="Another Card"}
Another description.
::
:::

Available Colors

Available Icons

Phosphor uses the Lucide icon library. Any Lucide icon name works in the icon attribute. Common ones for docs:

Full list at lucide.dev/icons.

Decision Grids

Decision grids help users pick the right option based on their situation. They render as styled tables with hover highlighting.

Decision Grid Syntax

:::decision-grid
| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| Row 1 cell | Row 1 cell | Row 1 cell |
| Row 2 cell | Row 2 cell | Row 2 cell |
:::

The content inside is a standard Markdown table. The :::decision-grid wrapper applies the styled grid layout instead of a regular table.

Command Blocks

Command blocks document CLI commands with a styled header, usage line, and flag reference table. Ideal for tool documentation.

Command Block Syntax

:::command{title="command-name" usage="command-name [args] [flags]"}
::flag{name="--flag-name" short="-f"}
Description of what this flag does.
::

::flag{name="--another" short="-a"}
Another flag description.
::
:::

The title attribute sets the command name in the header. The usage attribute sets the usage line. Each ::flag child has a name (long flag) and optional short (short flag).

Accordions

Accordions hide content behind a clickable summary. Useful for FAQs, optional details, or long reference sections that would clutter the page.

What Markdown syntax does Phosphor support?

All standard Markdown: headings, paragraphs, bold, italic, inline code, links, images, lists (ordered and unordered), code blocks, tables, and horizontal rules. Plus the extended component syntax documented on this page.

Can I nest components inside accordions?

Yes. Accordion bodies support all standard Markdown formatting including code blocks, lists, bold, italic, and inline code. The body content is processed as regular Markdown.

How do accordions render?

Accordions use the HTML <details> and <summary> elements with Phosphor styling. They're accessible, work without JavaScript, and animate smoothly.

Accordion Syntax

:::accordion{title="Visible summary text"}
Hidden content that appears when the user clicks.
Supports **Markdown** formatting and `code`.
:::

Pipeline Diagrams

Pipelines visualize multi-step processes as numbered stage nodes connected by arrows.

Pipeline Syntax

:::pipeline
Stage 1 -> Stage 2 -> Stage 3 -> Stage 4
:::

Stages are separated by ->. Each stage gets a numbered node (01, 02, 03...) and they're connected with arrow icons. The pipeline scrolls horizontally if it overflows on narrow screens.

Hero Sections

The hero section is typically used on the homepage (index.md) to create a prominent landing area with a title, description, and action buttons.

Hero Syntax

:::hero{badge="Badge Text"}
# Main Title With **Accent Words**
Description paragraph below the title.

[Primary Button](url){.primary}
[Secondary Button](url){.secondary}
:::

Key details:

• The badge attribute creates a small pill label above the title
• The # heading becomes the hero title (h1)
• Words wrapped in **double asterisks** get the teal accent color
• Lines starting with [ become action buttons
• {.primary} makes a teal filled button, {.secondary} makes an outlined button
• Regular text lines become description paragraphs

Page Structure

---

Recommended Page Layout

Every page should start with either a :::hero block (for the homepage) or a ## Section heading. Here's the recommended structure:

## First Section

Introductory paragraph for this section.

### Subsection

More detailed content here.

## Second Section

Another section with its own content.

### Another Subsection

And so on.

Section IDs

Phosphor automatically generates URL-friendly IDs from your headings:

These IDs are used for:

• Sidebar navigation anchor links
• Table of contents links
• Direct URL linking (page.html#section-id)
• Search result navigation

Table of Contents

The table of contents (TOC) appears automatically on wide screens (1200px+) as a sticky sidebar on the left side of the content area. It lists all ## and ### headings on the current page with scroll spy highlighting.

You don't need to do anything to enable it — Phosphor generates it automatically from your headings.

Search

Search is also fully automatic. When you build your site, Phosphor extracts every heading and the surrounding paragraph content, generates a search index, and injects it into the search JavaScript. Users can:

• Click the search box in the sidebar
• Press / anywhere on the page to focus search
• Type to see instant results with fuzzy matching
• Navigate results with arrow keys
• Press Enter to jump to the result

Multi-Page Sites

For sites with multiple pages, structure your content across separate .md files. Each page becomes its own HTML file. Use the nav section in docs.yaml to define the sidebar navigation, and link between pages using .html extensions:

[See the reference](reference.html#commands)