Skip to content
Norn
Menu

norn-docs

A docs page: the sticky docs sidebar with site search above its list, the page title, its contents when it has two or more sections, the body in norn-rich-text, and the pager. Extends norn-base. When the page is 60rem wide or more, the contents are a sticky column at the end of the body. Narrower, they fold under their title, and the sidebar folds into a closed <details> under the sidebar's name. The search is live from a Pagefind index at pagefind/, or a web search of the site's host without one. Only the page body is indexed. The contents list comes from nornHeadings over the body: headingAnchors, which the plugin adds to Markdown, writes the anchored headings. With fewer than two, the layout leaves norn-toc out, so the page ships none of its CSS or JS. The sidebar's name ("Documentation") and the search label ("Search the docs") come from componentStrings under norn-docs, then English.

layout: norn-docs.webc a template, from @allons-y/webc-patterns

Examples

Color scheme
Width

Open on its own

Source
---
title: Getting started
order: 1
description: Install the project and run it once.
layout: norn-docs.webc
---
Install the project, then run it once to see it work.

## Install

```sh
$ npm install @example/core
```

## Run it

Call `greet` with a name.
Color scheme
Width

Open on its own

Source
---
title: Usage
order: 2
description: The everyday commands.
layout: norn-docs.webc
---
The everyday commands, in one place.

## Commands

| Command | Does |
| --- | --- |
| `example build` | Builds the site |
| `example serve` | Serves it locally |
Color scheme
Width

Open on its own

Source
---
title: Reference
order: 3
description: Every option, in one place.
layout: norn-docs.webc
---
Every option, in one place.

> Options are read from `example.config.js`.

Props

The plugin's props mapping sets them on each page, and the layout reads them as $data.norn.

NameTypeDescription
docs { href: string, title: string, icon?: string }[] The docs pages, in order. icon names a sidebar norn-icon.
prev { href: string, title: string } Falls back to the page before this one in docs, by nornAdjacent.
next { href: string, title: string } Falls back to the page after this one in docs.
search { bundle?: string, site?: string } | false Pagefind's script (falls back to /pagefind/pagefind.js) and the host the plain form searches (falls back to the host of url; a url with a scheme that does not parse fails the build). false leaves the search out.

Slots

NameDescription
default The page body, in norn-rich-text. Its anchored headings make the contents.

Tokens

The global tokens from tokens.json the component reads. Set one in a project's tokens.css to change it everywhere.

Type a value to try it in every example above. Reset puts the default back.

Token Type Default Override
--norn-ui-accentThe brand color, shared by every component. <color> #2346d4
--norn-space-mMedium spacing step. <length> 1.25rem