Conventions

This is the most powerful bit: we crawl your repository looking for a handful of useful files and use them to build the website. Whenever possible we recommend following these conventions first, and reaching for configuration only when you need to override something.

Everything below is detected automatically from a public repository, no config required. Each item links to its matching configuration option, which always takes precedence over what we detect.

name

Your project's short identifier. It comes from the Github repository name, tidied up: emoji are stripped, dashes become spaces, and each word is capitalized, so the repo my-cool-lib becomes My Cool Lib. It's the shortest possible label for your project, with no tagline or icon, and appears in the browser-tab title (and, on paid plans, next to the logo in the navbar). Override it with the name option.

title

A longer identifier that can carry your tagline. It defaults to the same value as name, but this is where the marketing goes: it's used as the main title in Google search results and as the headline on social share cards. Set the title option to give search engines and link previews something richer than the bare project name.

description

A short paragraph summarizing what the project does and why it matters, taken straight from your repository's Github description. It appears in the Google search snippet and the social share-card description. Emoji are stripped and whitespace normalized. Override it with the description option.

logo

We look for a file named favicon or logo with a .svg, .png, .jpg, .jpeg or .ico extension, preferring files closer to the repository root. The image becomes both the browser-tab favicon and (on paid plans) the logo shown next to your project name in the navbar. If none is found, we fall back to the Documentation Page icon. Point at a specific file or URL with the logo option.

hero

The hero is the image used for social share cards, the preview that appears when your docs are linked on Twitter, Slack, Facebook, and so on (the Open Graph and Twitter image). We look for a file named hero or splash (same extensions as the logo); failing that we use your repository's Github social-preview image, and as a last resort an automatically generated card. Set the hero option to use a specific image.

documentation

If you don't set documentation explicitly, we pick the source of your docs automatically:

1. A documentation/ folder, if present.
2. Otherwise your readme.md.

A folder is read recursively and every .md file inside it is concatenated into a single page, in order: alphabetically, with top-level files before nested ones. Because the order is alphabetical, prefixing files with numbers (1. Intro.md, 2. Usage.md) is the easiest way to control the sequence. For full control over which files and folders are included, and to split your docs into multiple pages, use the documentation option.

blog

If your repository has a top-level blog/ folder, its markdown files are published as a blog automatically: the index at /blog, each post at /blog/<slug>, and a Blog link added to the navigation. Point at a different folder with the blog option, and see the Blog guide for the per-post front-matter (title, description, date, image) and how posts are ordered.

menu

The top-right navigation menu is the one thing here that is not auto-detected. It's used on custom domains and must be set with the menu option.