Logo Vertical Docs

GitHub

Site configuration

Set the site name, its description, its public address, the repository link and the accent colour, and replace the logo, favicon and share image.

A site is one docs folder: docs/docs.config.json, docs/public/ and docs/content/ with the pages. Change docs.config.json for the name, the description, the public address, the repository link, the accent colour, the header tabs and the home page, and replace the files in public/ for the logo, the favicon and the share image.

docs.config.json

init writes the file with placeholders:

{
  "name": "Your Docs",
  "description": "What your product does, in one sentence.",
  "url": "https://docs.example.com",
  "repo": "https://github.com/your-org/your-repo",
  "accent": "#171717"
}
Field Used for
name The text next to the logo and the end of the browser tab title.
description The summary under the name in /llms.txt.
url The public address of the site: https:// and the host name, with no path and no slash at the end. The canonical URL and the share tags of every page start with it, and so does every link in /sitemap.xml, /robots.txt and /llms.txt.
repo The GitHub link in the header.
accent The colour of links, the current page in the sidebar, the focus ring and the edge of a callout.
tabs Optional. The folders that become header tabs. A site without tabs has one sidebar with every page.
home Optional. true shows the first page as a home page, without the sidebar.

Docs folder

Every command reads one docs folder: the pages and their images in content/, and docs.config.json and public/ beside it. The folder is docs in the folder where the command runs. Name another folder after the command:

npx vertical-docs check website

This command builds the pages in website/content/ with website/docs.config.json and the files in website/public/, and writes the site to website/dist/.

npx vertical-docs init website writes a docs folder with that name, and names the folder in the two workflows.

Accent colour

accent is one CSS colour, such as #0070f3. The site keeps the hue and adjusts the lightness for each theme, so the same colour is readable on the light and on the dark background.

The default, #171717, is a neutral colour: the site is black on white in the light theme and white on black in the dark theme.

Header tabs

tabs is a list of folders directly under docs/content/. Each folder becomes a tab in the header, in the order of the list, and the sidebar shows only the pages of the tab that holds the page being read.

"tabs": ["guides", "reference"]

With this line the header has three tabs. The first tab is always “Overview”: it opens the home page and holds every page outside the listed folders. The other two take their names from the titles of docs/content/guides/index.md and docs/content/reference/index.md, and each opens that page.

In the sidebar of a folder’s tab, the folder’s index page comes first and the folder’s pages and groups follow. The previous and next links at the end of a page stay inside the tab. On a small screen the tabs are in the menu, above the pages. On a wide screen the tabs are one row that does not wrap, so keep the list short.

Tabs change the header and the sidebar only. The address of every page, the search and /llms.txt stay as they are without tabs.

The build stops for a name that matches nothing directly under docs/content/. The message names the file to add, with its path from the docs folder:

docs.config.json lists the tab "guides", but content/guides/index.md does not exist. A tab is a folder directly under content/, and its index page names the tab.

Home page

home set to true shows the first page of the site, docs/content/index.md, as a home page: one centred column under a large title, without the sidebar, the list of headings and the previous and next links.

"home": true

The header of the home page has a “Docs” link to the first of the other pages, and the sidebar of every other page leaves the home page out. The name of the site in the header opens the home page.

The home page is plain Markdown like every page. Three things look different on it:

  • The first code block is the command to start with: a narrow block with a $ before the command.
  • A list is a grid of entries, and the bold words at the start of an entry are its title.
  • An image has a frame.

The address of the page, its Markdown copy, the search and /llms.txt stay as they are without home.

Logo and favicon

File Shown
docs/public/logo.svg In the header, 20 pixels high, next to the name.
docs/public/favicon.svg In the browser tab.
docs/public/share.png In the preview of a link to the site, in a chat or on a social network. Make it 1,200 by 630 pixels.

The logo is placed in the page as inline SVG. Draw it with fill="currentColor" and the logo takes the text colour of the theme.

Old addresses

A site that moves keeps its old addresses in docs/public/_redirects. Each line is the old path, the page that replaces it and 301:

/getting-started / 301

Cloudflare answers a request for the old path with a permanent redirect when the site runs as a Worker. vertical-docs check fails for a line that points to no page or that does not end with 301.

View this page as Markdown