Site config reference
Every key of site.config.ts, the file that sets the structure of a SHIP site. Each key is required, and an unknown key stops the build.
site.config.ts is at the root of the site repository. It exports the config through defineSiteConfig, which checks it when the file loads.
import { defineSiteConfig } from "@lets-ship/site/config";
export const site = defineSiteConfig({
origin: "https://example.com",
titleSeparator: "|",
sections: {
website: { path: "/", content: "./content/pages" },
blog: false,
docs: { path: "/docs", content: "./content/docs", editUrl: false, tabs: [] },
},
nav: [{ label: "Docs", href: "/docs" }],
mdxComponents: [],
footer: { columns: [], social: "brand-links", badge: true },
features: { search: true, markdownCopies: true, llms: true },
integrations: { analytics: { provider: "none" } },
});The config has no defaults. Each key states one choice, so a reader of the file sees every choice. The site name, the description, the colours and the fonts are not in this file, because they come from the brand DNA.
Editor support
The JSON Schema of the config is at https://letsship.ai/schema/site.json. SHIP generates it from the same schema that ship-site checks the config with. The schema has no rules that join two keys. The build checks those, for example two sections at one path.
Top-level keys
| Key | Type | Effect |
|---|---|---|
origin | string | The https origin of the site in lowercase, without a path and without a slash at the end. Canonical links, feeds and the sitemap use it. |
titleSeparator | string, 1 to 3 characters | The mark between a page title and the site name, for example `" |
sections | object | The website, blog and docs sections. See below. |
nav | array of { label, href } | The links in the header. |
mdxComponents | array of names | Your own MDX components, on top of the allow-list. Each name starts with a capital letter. |
footer | object | The footer columns, the social links and the badge. See below. |
features | object | The optional files. See below. |
integrations | object | The analytics provider. See below. |
Sections
Set each section to an object to turn it on, or to false to turn it off. At least one section must be on, and no two sections can have the same path. A path starts with / and has lowercase segments.
sections.website
| Key | Type | Effect |
|---|---|---|
path | path | Where the website pages start, usually /. |
content | string | The folder of the pages, for example ./content/pages. A file index.mdx is the page at the section path. |
sections.blog
| Key | Type | Effect |
|---|---|---|
path | path | Where the blog index is, for example /blog. |
content | string | The folder of the posts. |
categories | array, at least one | Each category has a slug, a name for its tab, and a title and a description for its page. Each post names one category. |
authors | array, at least one | Each author has a name, a path for the author link, a bio and an x. The x key is the X handle of the author, for example @name, or null. A post by an author with a handle names that handle in its X card. |
feeds | boolean | Builds the RSS, Atom and JSON feeds at the site root. |
layout | "list", "grid" or "magazine" | How the index shows the posts. The magazine layout shows the featured posts first. |
A category page exists only when at least one post is in that category.
sections.docs
| Key | Type | Effect |
|---|---|---|
path | path | Where the docs start, for example /docs. |
content | string | The folder of the docs pages, with meta.json files for the sidebar order. |
editUrl | URL or false | The base of the "Edit on GitHub" link, for example https://github.com/acme/site/blob/main. The link adds the content folder and the file path. false shows no link. |
tabs | array of { label, path } | Tabs above the sidebar. Use an empty array for no tabs. |
Footer
| Key | Type | Effect |
|---|---|---|
columns | array of { title, links } | Link columns. Each link is { label, href }. |
social | "brand-links" or "none" | Shows the links from the brand DNA, or no social links. |
badge | boolean | Shows the "Built with SHIP" badge. When it is true, the build checks that each page shows it. |
Features
| Key | Type | Effect |
|---|---|---|
search | boolean | Builds the static search index and shows the search dialog. |
markdownCopies | boolean | Builds a Markdown copy of each page under /md/ and links it from the page. |
llms | boolean | Builds /llms.txt and /llms-full.txt. Needs markdownCopies. |
A feature that is off has no route in the build, so the site serves a 404 for its files.
Integrations
integrations.analytics names one analytics provider. Each page loads the script of that provider in its head, with the key you give.
| Value | Effect |
|---|---|
{ provider: "none" } | No analytics script. |
{ provider: "plausible", key } | Plausible. The key is the domain of the site in Plausible. |
{ provider: "umami", key } | Umami Cloud. The key is the website ID. |
{ provider: "fathom", key } | Fathom. The key is the site ID. |
How is this page?