Navigation & Structure

Stele turns your repository's file structure into a navigable website. This page explains how URLs map to files, how landing pages are resolved, and how linking works.

URL structure

Your site is served at https://<slug>.stele.axelerant.tech. File paths map directly to URLs with the renderable extension stripped:

Renderable files (.md, .html, .htm, .tsx, .jsx) have their extension removed. Static assets keep their full path including the extension.

Directory URLs (ending with /) resolve to a landing page or directory listing.

Landing page resolution

When you visit a directory — the site root / or any subdirectory like /docs/ — Stele resolves which page to show. It checks in this order:

1. .stele.yml landing — the file specified in landing in the directory's .stele.yml (or root .stele.yml for /)
2. index.html or index.htm
3. index.jsx or index.tsx
4. index.md
5. README.md (case-insensitive)
6. Frontmatter flag — a Markdown file with stele.landing: true (or stele: { landing: true }) in its YAML frontmatter
7. Directory listing — an auto-generated page listing the directory's contents

The first match wins. For most repos, the root README.md becomes the home page with no configuration needed.

Overriding with .stele.yml

To set a specific landing page for a directory, add a .stele.yml in that directory:

# docs/.stele.yml
landing: getting-started.md

For the site root, use the root .stele.yml:

# .stele.yml (root)
landing: docs/overview.md

Paths are always relative to the directory the config lives in.

Overriding with frontmatter

In any Markdown file, add stele.landing: true to its frontmatter:

---
stele:
  landing: true
---

# This page will be the landing for its directory

If both a .stele.yml landing and a frontmatter flag exist for the same directory, the .stele.yml wins.

Both spellings, stele.landing: true on one line and the nested form above, work. Only the boolean true counts: "true", yes and 1 do not. The flag is the last thing Stele tries, so an index.* file or a README.md in the same directory also wins over it. When two files in one directory are flagged, the first by path wins.

Collections on a landing page

When a directory is a collection (a folder of ADRs, runbooks or audit findings), Stele adds a generated list of its items to the landing: below a Markdown landing such as README.md, or as the landing itself when the directory has none. An HTML, TSX or JSX landing is always served as written, with no list. See Where the list appears.

Linking between pages

Relative links in Markdown and HTML files are automatically rewritten to work on the rendered site. (For HTML, links to other pages also open as a whole page rather than inside the artifact's frame; see Linking between HTML pages.) Write links the same way you would in any Markdown file:

See the [overview](./overview.md) for context.
Check the [architecture docs](../architecture/design.md).
Browse the [audits directory](./audits/).

How links are resolved

Rules:

• Relative paths are resolved against the current file's directory
• Renderable extensions (.md, .html, .tsx, .jsx) are stripped from the URL
• Non-renderable files (images, PDFs, etc.) are served at their original path
• External URLs, anchors, and mailto: links pass through unchanged
• Cross-repository links are not supported — links only resolve within your repo

Linking to headings

Every Markdown heading gets an auto-generated anchor based on its text:

## My Section Title

Link to it with:

[Jump to section](#my-section-title)

From another file:

[See that section](./other-file.md#my-section-title)

Sidebar

The default theme has no sidebar. A folder in the guide theme gets one, listing every page under the folder with the page you are reading marked. Stele builds it from folders, titles and frontmatter weight, and a nav: list in .stele.yml can set the groups. See Themes.

File browser

Stele includes a built-in file browser at /_browse (by default). It shows your site's full directory tree in a browsable interface with:

• Breadcrumb navigation
• File type icons and extension badges
• Click-through to any rendered page or asset

Configuring the file browser

In the root .stele.yml:

# Move to a different path
file_browser:
  path: /_files

# Disable entirely
file_browser:
  enabled: false

The path must start with /_. This setting only works in the root config.

Directory listings

When a directory has no landing page (no index.*, no README.md, no .stele.yml or frontmatter override), Stele shows an auto-generated directory listing. This listing includes:

• Subdirectories (listed first)
• Renderable files in alphabetical order
• Breadcrumbs for navigating back up

This ensures you never hit a 404 when navigating into a directory — there's always something to see.