Themes

A theme decides how Stele draws your pages: Markdown pages, the lists Stele generates for collections, the file browser and error pages. Hand-written HTML is never restyled. An HTML page can opt in to a theme's look and sidebar, as described below.

Stele has two themes:

default: clean black-on-white pages in Stele's own type, with a dark mode that follows the reader's system. Every site uses it unless a .stele.yml names another theme.
guide: the design of Axelerant's codebase guides. Each section is a numbered card on a grey page, and a sidebar lists every page in the guide. Pages show their place in the guide, and there are previous and next links at the bottom. It suits a set of pages meant to be read in order: a codebase guide, onboarding notes, an analysis. It is light only for now.

Choosing a theme

Name the theme in the .stele.yml of the folder it should cover:

# In docs/codebase-guide/.stele.yml:
theme: guide

The setting covers the folder and everything below it. A subfolder can choose differently with a .stele.yml of its own, including theme: default to go back to the plain look. The nearest setting wins.

One Markdown page can choose for itself in its frontmatter:

---
theme: guide
---

A theme name Stele does not know is a warning on the site's overview in the portal. The folder keeps the theme it would otherwise have. See Validation.

The guide theme

A Markdown page in the guide theme is laid out like this:

The header shows where the page sits in the guide, then its title (the page's first # heading) and the page's description from frontmatter, as a short summary under the title. Owner, type and verification, when the frontmatter has them, appear below the title as they do in the default theme.
Each ## section becomes a numbered card. Anything before the first ## becomes an opening card. Section anchors stay as they are, so existing links to #a-heading keep working. Emphasis in the title (# Which site the code *describes*) is drawn in the guide's accent colour.
The sidebar lists the guide's pages, with the page you are reading marked and its own sections listed under it. The sidebar highlights the section you are reading as you scroll. On a narrow screen it becomes a drawer, and on a wide one a button hides it.
Previous and next links at the bottom follow the sidebar's order.

---
description: The repository holds three code lines that describe three different sites.
weight: 1
---

# Which site the code *describes*

## What the repository is

A starter theme grown for four years.

Callouts

Write a callout with GitHub's alert syntax. It works in both themes, and GitHub shows it the same way:

> [!WARNING]
> **Two code lines, not one.** Develop and Production have drifted.

The kinds are NOTE, TIP, IMPORTANT, WARNING and CAUTION. In the guide theme, WARNING and CAUTION are orange, TIP is green, and NOTE and IMPORTANT are blue. Starting a warning with a bold clause gives the reader the point before the detail.

The sidebar belongs to a navigation root: the folder whose .stele.yml names the theme, or declares nav:. Every page under that folder is listed, with no list to keep up:

the root's own pages first, then one section for each folder below it, headed by that folder's landing page title (or its name when it has no landing);
within a section, the folder's landing first, then pages in order of their frontmatter weight (lower first), then by title;
the root's landing is the guide's name at the top of the sidebar.

A page appears under its title: the frontmatter title, else its first heading, else its file name. Only pages the reader may open are listed.

A subfolder can start a sidebar of its own while keeping the theme, by declaring nav: (even an empty list) in its .stele.yml.

Curating the order with `nav:`

When folders are not how you want the pages grouped, list groups in the root's .stele.yml:

# In docs/codebase-guide/.stele.yml:
theme: guide
nav:
  - group: Orientation
    pages:
      - path: index.md
        title: Overview
  - group: The website
    pages:
      - wp-repository.md
      - wp-content-model.md
  - group: Related
    pages:
      - ../findings/

Each entry is a page path, or a group with a list of pages. Pages listed at the top level, outside any group, appear without a heading.
A page is a path, or a block with path and a title to show instead of the page's own.
Paths are relative to the folder. A path ending in / means that folder's landing page. A path may point outside the root, as in a "Related" group, but previous and next links stay inside it.
Pages the list leaves out still appear, after the curated groups, grouped by folder as above. Adding a page never needs an edit here to show up.
Paths that match no page are left out.

A mistake anywhere in nav: makes Stele ignore the whole list, show the derived sidebar instead, and put a warning with the line on the site's overview in the portal.

HTML pages

Hand-written HTML is drawn exactly as written. To use the guide theme in an HTML page, link its files at their fixed addresses, which work from any folder depth. Then leave an empty nav for Stele to fill:

<head>
  <link rel="stylesheet" href="/_stele/themes/guide/theme.css">
  <script src="/_stele/themes/guide/theme.js" defer></script>
</head>
<body>
<nav data-stele-nav></nav>
<div class="wrap">
  <header>
    <div class="crumb">codebase-guide / wp-repository</div>
    <h1>Which site the code <em>describes</em></h1>
    <p class="thesis">One sentence on what this page establishes.</p>
  </header>
  <section class="card">
    <h2><span class="no">01</span>What the repository is</h2>
    <p class="lead">The section's point in one line.</p>
    <div class="callout warn"><b>Two code lines.</b> The detail.</div>
  </section>
</div>
</body>

Stele replaces <nav data-stele-nav></nav> with the same sidebar a Markdown page gets, for the page's navigation root, with the page marked. The nav must be empty; a nav with anything inside is left alone. Links in it open as whole pages, like any link between HTML pages.

The stylesheet carries the guide's classes: header .crumb, .thesis and .meta; section.card with h2 .no and p.lead; .callout.warn, .info and .good; .pill in hot, blue, green, violet, teal and amber; .tablewrap; .cols with .col; .stage with .cap; .next; and footer. HTML pages number their own sections and write their own previous and next links.

Not yet

The guide theme has no dark mode.
A site cannot change a theme's colours or fonts, for example to a client's brand.