Making a site

How to make a site — a project's documentation as many pages, with a sidebar built from their Topics sections and, if you want one, a navbar across the top. It covers the site's document file, its root page, how pages join the sidebar, and the navbar, logo and theme switch. It is a task article under the viewer; the document file in general is on Writing a document.

A site

kind: site
title: My project
root: README.md
logo: logo.svg
navbar:
  Docs (book-open): README.md
  Getting started (rocket): getting-started.md
  (github): https://github.com/me/my-project

Run it from the top of the repository, so pages can link anywhere in it:

$ devpage docs
My project → http://localhost:3030

The root page and the sidebar

The root page is where the site opens and the top of its sidebar. A page joins the sidebar when a page already in it lists it in a ## Topics section at its end — the root's Topics are the first level, their Topics the next:

## Topics

- [Getting started](getting-started.md) — install it and run a first page.
- [Guide](guide/README.md) — the tasks, one page each.

Links anywhere else in a page work as ordinary links and never change the sidebar. How Topics shape the tree — groups, order, labels, repeated pages — is on Organizing navigation.

The navbar, the logo and the theme switch

• navbar puts links across the top: Label: target, a Lucide (icon) after a label, a nested map for a dropdown, (icon) alone for an icon-only link (the navbar).
• sidebar: false hides the sidebar — for a site navigated by its navbar alone.
• logo shows an image before the title and makes it the tab's icon.
• The theme switch and the comment-mode button (unless comments are off) sit at the right end of the navbar, or in the top-right corner without one (choosing a theme, Comments).

A real site to copy

These docs are a site: docs/devpage.yml with a navbar, a logo, widgets and a sidebar built from Topics, starting at the landing page. Every field is in the configuration reference.