SHIP Sites
One site engine for a website, a blog and docs. Your brand DNA sets the look, and site.config.ts sets the structure.
SHIP Sites builds a website, a blog and docs as one static site. Two npm packages do the work. @lets-ship/site is the site engine, on Next.js and fumadocs. @lets-ship/brand-dna reads your brand file and compiles it into a theme. Both packages are MIT licensed.
The engine has no colours, fonts or names of its own. Every value that a reader sees comes from one of three inputs in your repository.
| Input | File | What it holds |
|---|---|---|
| Brand | brand/brand.dna.json | The name, the description, the links, the colours, the fonts and the logos. |
| Structure | site.config.ts | The sections, the navigation, the footer and the optional files. |
| Words | content/ | The pages, the posts and the docs, in MDX. |
Start a site on SHIP
SHIP has a template on GitHub for each kind of site: a website, a blog and docs. Each template turns on one section. In onboarding, you make a repository from a template, and the first mission builds the site with your brand. SHIP then hosts the site at https://<slug>.letsship.app, where <slug> is the site address that you choose.
- Your first mission follows onboarding from the choice of a template to the live site.
- Manage a site covers the Sites page, rollback, unpublish and the rules of your plan.
- Leave SHIP Sites hosting shows how to serve the same build from another host.
The three sections
A site can use one, two or all three sections. Each section has its own path.
- Website: pages from
content/pages/, made of blocks such as a hero, a price table and questions with answers. - Blog: posts from
content/posts/, with categories, featured posts, feeds and article structured data. - Docs: pages from
content/docs/, with a sidebar frommeta.jsonfiles, a table of contents, previous and next links, and an edit link.
One section can be at /. For example, a website at / with a blog at /blog and docs at /docs is one site. The config refuses two sections at the same path, and the build refuses a site with no page at /.
Build a site
The ship-site command checks your inputs, builds the static site into out/ and checks the output.
npx ship-site buildThe build stops at the first problem and names the file and the fix. These are the checks:
- The config matches the schema. The build stops on an unknown key, and on a key that is not there.
- The brand DNA passes its lint.
- Each MDX file parses, and it uses only components from the allow-list.
- Each colour in the output comes from the brand DNA, and each font comes from the brand's fonts.
- If the config turns the badge on, each page shows it.
Two builds of the same inputs give the same bytes. The file out/.ship-site.json records the hash of the inputs and the hash of the output.
The other commands
| Command | What it does |
|---|---|
ship-site check | Runs the checks without a build. |
ship-site theme | Compiles the brand into .ship-site/theme and public/_brand. |
ship-site dev | Compiles the brand and starts the Next.js dev server. |
ship-site serve out | Serves a built site with the same rules as the hosting. |
Exit code 1 is a problem in your own files. Exit code 2 is a wrong command line, and exit code 70 is a failed build step.
Optional files
The config turns each optional file on or off. A file that is off is not in the build at all.
| Feature | Files |
|---|---|
features.search | The static search index at /api/search and the search dialog. |
features.markdownCopies | A Markdown copy of each page under /md/, linked from the page. |
features.llms | /llms.txt and /llms-full.txt, which link the Markdown copies. |
sections.blog.feeds | /feed.xml, /atom.xml and /feed.json. |
The site also has a sitemap and a robots.txt. features.llms needs features.markdownCopies, because llms.txt links the copies.
Report a site
To report a site that SHIP hosts, use the report form. You can also write to abuse [at] letsship.ai. A person at SHIP checks each report and sends you the result by email. If SHIP suspends or removes a site, its owners get the reasons and can appeal.
Next steps
How is this page?