Content Formats

Stele renders four file types as full pages. All other files (images, fonts, PDFs, CSS, JS) are served as static assets at their repository paths.

Markdown (.md)

Stele renders GitHub-flavoured Markdown with the following features:

• Tables — standard GFM pipe tables
• Task lists — - [x] and - [ ] checkboxes
• Strikethrough — ~~text~~
• Autolinks — bare URLs are automatically linked
• Syntax highlighting — fenced code blocks are highlighted with GitHub's light palette, or its dark one when the reader's system is in dark mode
• Callouts — GitHub's alert syntax (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) is drawn as a callout. See Themes
• Mermaid diagrams — code blocks tagged with ```mermaid are rendered as diagrams in the browser
• Heading anchors — every heading gets a slug-based anchor (e.g. ## My Section becomes #my-section) and links to itself, so a reader can copy a link to it

Frontmatter

Markdown files can include YAML frontmatter. Frontmatter is parsed but not displayed on the page.

---
title: Architecture Overview
description: High-level system design
stele:
  landing: true
---

# Architecture Overview

Content starts here...

These frontmatter fields have special meaning on any page:

• title is the page's title in the browser tab and wherever Stele lists the page, ahead of the first # heading.
• stele.landing: true marks the file as the landing page for its directory. See Navigation & Structure for details.
• theme draws this page in another theme than its folder's.
• description is the summary under the title in the guide theme.
• weight is a number that orders the page in the guide theme's sidebar, lower first.

In a collection (a folder of ADRs, runbooks or audit findings), Stele also reads each type's own fields, such as status, date or severity, to build the folder's list.

Mermaid diagrams

Wrap your diagram source in a fenced code block with the mermaid language tag:

```mermaid
flowchart LR
    A[Push to Git] --> B[Webhook fires]
    B --> C[Stele syncs]
    C --> D[Site updated]
```

Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, and more. The full syntax is documented at mermaid.js.org.

Linking between files

Relative links in Markdown work as you'd expect. Stele rewrites them to point to the correct rendered URLs:

See the [overview](./overview.md) for details.
Check the [audits](../audits/) directory.

Links to non-renderable files (images, PDFs, ZIPs) serve the file directly. External URLs and anchor links are left unchanged. See Navigation & Structure for the full rules.

HTML (.html / .htm)

HTML files are served as-is inside an isolated iframe. This prevents styles and scripts from one HTML page from interfering with Stele's chrome or other pages.

The iframe sandbox allows scripts and same-origin access, so interactive HTML pages work normally. It also lets a click on a link navigate the whole page, which is how links between pages work (below); a script cannot navigate the page on its own. Links with target="_blank" open a new tab, and the page there is not sandboxed.

Sibling assets — images, stylesheets, scripts, fonts — are served at their repo paths, so relative references from your HTML continue to work:

<!-- In docs/report.html -->
<link rel="stylesheet" href="./styles.css">
<img src="./diagram.png">
<script src="./chart.js"></script>

As long as styles.css, diagram.png, and chart.js are committed alongside report.html, they resolve correctly.

Linking between HTML pages

Write ordinary relative links between your HTML files, exactly as you would for a static site:

<!-- In proposal/scope.html -->
<a href="pricing.html">Pricing</a>
<a href="../audit/summary.html#findings">Audit findings</a>
<a href="index.html">Back to the proposal</a>

Stele rewrites every link that points at another page of the site — HTML, Markdown or React — to that page's rendered URL (/proposal/pricing, /audit/summary#findings, /proposal/) and opens it as a whole page rather than inside the iframe. The address bar always shows the page you are reading, so its URL can be copied, shared and refreshed, and Back and Forward work. Query strings and #fragments are kept. The same extension rules apply as for Markdown links: a page whose basename is shared with another file (report.md beside report.html) keeps its extension so the link opens the right one.

Left exactly as written: external links, mailto: and other scheme links, #anchor links within the page (see below), links to assets, links with download, and links aimed at a named frame. A link with target="_blank" gets the rendered URL and still opens a new tab.

Anchors and deep links

Same-page links (<a href="#pricing">) and deep links to a section (/proposal/#pricing) work as they would on a static site. The fragment lives in the address bar of the page around the iframe, and Stele scrolls the frame to the element with that id (or an <a name>) when the page opens, when you click a # link, and on Back and Forward. A click on a # link puts the fragment in the address bar, so a section can be copied and shared. If your page builds its content with a script after it loads, Stele waits for the element to appear, for up to ten seconds or until the reader scrolls.

A # link your own script already handles (it calls preventDefault()) is left to your script. Inside the frame location.hash is empty, because the document is about:srcdoc; read top.location.hash if a script needs the fragment.

You do not need any script of your own for this. Artifacts written before this was handled sometimes carry a snippet calling top.history.replaceState() to fix the address bar; it is now unnecessary and can be removed, though leaving it in does no harm.

If a script in your artifact navigates by setting location to another page of the site, Stele notices the page arriving inside the frame and shows it as a whole page instead, so frames never nest.

React components (.tsx / .jsx)

TSX and JSX files are rendered as standalone React components using Stele's fixed runtime. Your file must default-export a component that takes no required props:

export default function Dashboard() {
  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold">Project Dashboard</h1>
      <p>Content here...</p>
    </div>
  );
}

Components are compiled at sync time (when you push), not in the browser. Stele provides a pre-built runtime with React, Tailwind, charting libraries, and more — no package.json or build configuration needed.

See React Components for the full list of available libraries and how to use them.

Static assets

Files that aren't renderable (.md, .html, .htm, .tsx, .jsx) are served directly at their repo path. Common asset types:

You can link to assets from any rendered page using relative paths.

Generated content (LikeC4, D2, etc.)

Diagram source files like .c4 / .likec4 (LikeC4) and .d2 (D2) aren't rendered directly. Instead, Stele can run a build command for the folder containing them and serve the generated HTML/SVG output. Both likec4 and d2 are pre-installed in the build environment.

Set this up via a .stele.yml build: block in the diagram folder. See Configuration → build for the full reference and copy-paste examples.

File size limit

Files larger than 25 MB are excluded from indexing and won't be served. Keep large binaries out of your repo or use Git LFS.