Entry format

Atlas expects each nav entry in pipe syntax:

- Introduction | introduction
- GitHub | https://example.com/repo | external

Rules that matter

Cross-section links

Content pages can link to a nav entry by slug:

See [doc:command-build] for the main compilation command.
See [build command | doc:command-build] for a custom label.
See [build parameters | doc:command-build#parameters] for a subsection.

The Markdown renderer converts those links into client-side navigation anchors tied to the section slug and optional heading anchor.

Supported catalogs

Referencing an asset

Use the @asset[name] syntax inside content files:

@asset[logo-mark]

The Atlas Docs source in this repository uses that pattern for the introduction hero image and the pipeline diagram in How Atlas Works.

Current implementation note

The renderer resolves asset declarations into inline placeholders or <img> tags during Markdown rendering. Local SVG and image assets are now copied into the built site's assets/ directory during the build so ./assets/... references stay portable.

Frontmatter

Common frontmatter keys:

Heading and anchor behavior

Atlas assigns DOM IDs to ##, ###, and #### headings and supports explicit anchor overrides:

## Request options {id=request}
### Theme family {id=theme-family}

Those anchors let you target subsections with [doc:slug#anchor].

Directive blocks

The current renderer supports these purpose-built blocks:

Code blocks

Python code fences receive custom highlighting from highlight_code() in markdown.py. Other languages render without the Python-specific token styling.

Core types

models.py defines the repository's structural dataclasses:

Loader behavior

load_site() performs several normalization steps:

• repairs common mojibake patterns before YAML parsing
• tolerates pipe-style nav entries that are not valid YAML scalars by quoting them
• supports both a direct source root and a nested atlas_docs/ directory
• computes fallback breadcrumbs and label maps from navigation

Extensions over plain Markdown

Directive coverage

The current implementation handles feature_grid, cards, callout, method, selector_list, table, quick_links, reference_list, and example_pair.

Heading IDs

Atlas strips explicit {id=...} suffixes from the rendered heading text, but preserves them for the resulting DOM ID. If no explicit anchor is present, it slugifies the heading text.

Syntax highlighting

Python code fences are tokenized with repository-defined regex rules for comments, strings, decorators, classes, functions, keywords, and numbers. That means highlighting is deterministic and local to the project; it is not delegated to an external highlighter.

Examples in Markdown and browser output

Use example_pair when you want a single block that shows Atlas source on one side and the rendered browser result on the other.

Think of the examples below as a progression. Start with the smallest inline syntax, confirm what the browser output looks like, and then move on to the larger directives once the basics feel familiar.

We will start with links, because they are usually the first Atlas-specific syntax you add to a page.

See [doc:format-assets] for the asset catalog format.

This syntax creates a link to another section by slug. Atlas looks up the navigation label for that slug, so the browser output shows a reader-friendly title instead of the raw slug.

Open [the assets registry docs | doc:format-assets] for naming rules.

Use this version when the default nav label is not quite the wording you want in a sentence. The destination stays the same, but you control the text that appears in the paragraph.

The loader builds the `Site{ref=architecture-loader}` model before rendering.

Inline code references are useful when you want code-like formatting and a connection to another section at the same time. This works well for class names, functions, and important types that readers may want to explore next.

Asset reference

Markdown to browser output

Source

@asset[pipeline-figure]

Browser

An asset reference pulls a named image or SVG from assets.md into the page. This keeps prose cleaner, because authors can reuse short asset names instead of repeating file paths everywhere.

### Stable heading target {id=stable-heading-target}

Explicit heading IDs are helpful when you want a stable anchor that will not change if the visible heading text gets rewritten later. That is especially useful for deep links from other docs or saved bookmarks.

```python
from atlas_docs.loader import load_site

site = load_site(source_dir)
return site
```

from atlas_docs.loader import load_site

site = load_site(source_dir)
return site

Code fences still behave like normal Markdown, but Atlas adds local Python highlighting on top. That means you can mix standard Markdown habits with Atlas-specific syntax instead of learning a completely different authoring model.

Once the inline pieces make sense, the bigger directives are easier to read. Each directive starts with :::name, accepts its own structured body, and renders to a more polished UI block in the finished site.

:::feature_grid
### Cross-section links {icon=->}
Jump between sections with `[doc:slug]` syntax.

### Inline references {icon=#}
Attach interactive refs to code tokens with `` `name{ref=slug}` ``.
:::

feature_grid is a good first directive to study because the source stays very close to the final layout. Each mini-heading becomes one feature item, and the optional icon gives the card a small visual marker.

:::cards
### Source files {link=format-content}
See how section files map to navigation entries and frontmatter.

### Theme rendering {link=architecture-renderer}
Follow the last stage of the pipeline into HTML and CSS output.
:::

Cards are similar to a feature grid, but they are designed to feel more clickable and navigational. Use them when you want readers to branch into a few important follow-up sections.

:::callout info
Atlas transforms custom syntax before standard Markdown rendering runs.
:::

Callouts are the simplest way to emphasize a note without inventing custom HTML. They work well for warnings, tips, and short explanations that should stand apart from the surrounding body text.

:::method
load_site(source_dir, *, strict=False) -> Site
:::

The method directive is more specialized. It turns a function or API-style signature into a compact reference block, which makes architecture pages and API docs easier to scan.

:::selector_list
### `[doc:slug]`
Link to another Atlas section.

### `[label | doc:slug]`
Link to a section with author-defined text.
:::

selector_list works well when you need a small syntax reference. The left side shows the token or pattern, and the right side explains what that syntax means in plain language.

:::table
| Syntax | Purpose |
|--------|---------|
| `[doc:slug]` | Navigate to another section |
| `@asset[name]` | Render a named asset |
:::

Use a table when readers need to compare several patterns at once. This is a better fit than prose when the information is naturally organized into columns like syntax, purpose, and result.

:::quick_links
- [doc:architecture-loader]
- [doc:architecture-renderer]
- [Atlas repository](https://github.com/BrandonBahret/Static-Documentation-Generator)
:::

quick_links turns a short list of destinations into a cleaner navigation block. It is a good choice near the top or bottom of a section when you want to guide readers toward the next useful pages.

:::reference_list
- [doc:format-content] for section frontmatter and headings
- [doc:format-assets] for asset registration
- [doc:architecture-renderer] for final HTML output
:::

reference_list is similar, but it reads more like supporting material than navigation. Use it when you want a small "read this next" list tied to the current topic.

After working through these pairs, you can usually predict how a new block will render just by reading the Markdown. That is the main goal of example_pair: it turns the page into a side-by-side sandbox instead of a purely textual specification.

Build path

build_site() does four main things:

1. Loads the site model from source files.
2. Resolves the active theme and optional alternate color-scheme variant.
3. Concatenates CSS and bundled JavaScript modules.
4. Renders templates/base.html.j2 with the site payload and serialized config.

Theme family behavior

Atlas currently ships one theme family with two variants:

If the chosen theme belongs to a known family, Atlas can resolve an alternate theme name and expose a color-scheme toggle in the generated site configuration.

Metadata overrides

The theme loader lets site metadata override:

• accent color for the active scheme
• display, body, and mono fonts
• font source URL
• default color scheme

Search and navigation payload

The renderer serializes a JSON config object with section metadata, theme metadata, search copy, and feature flags. The client-side JavaScript uses that payload to drive section routing, search indexing, and user settings.