Content

All of a kit site's content is in src/content/, as Markdown and YAML files. Every file names its language before its extension, such as about.en.md.

src/content/
  pages/
    home.en.md  about.en.md  services.en.md  404.en.md
    services/
      painting.en.md
  news/
    spring-painting-dates.en.md
  settings/
    site.en.yml

Pages

A page is a Markdown file in src/content/pages/, and its URL follows its path: pages/services/painting.en.md is served at /services/painting, and home.en.md at /. Its frontmatter has the page's title, its description for search engines, and an ordered list of sections. Its body stays empty.

---
title: Services
description: Kitchen and bath renovation, repairs and painting in Fenwick Falls.
sections:
  - id: t85a
    type: hero
    title: Everything your home needs, from one trusted team
    variant: page
  - id: o8kv
    type: split
    title: Kitchen & bath renovation
    image: /assets/images/kitchen.jpg
    imageAlt: A kitchen with cream cabinets
    variant: image-right
---

Each section has a type and a stable id, which stays the same when sections move, so a change to one section can be reviewed, and in a site with several languages, matched to its translations. Get a new id for a page with:

npm run section-id -- src/content/pages/services.en.md

A variant changes how a section is laid out, and a tone which background it sits on, where its type has them.

Section types

The library's section types:

Type	For
`hero`	the page's opening, or a page header
`rich-text`	formatted text
`collection-list`	entries of a collection, such as the latest blog posts
`services-grid`	services or values as cards
`gallery`	photos with captions
`testimonials`	customer quotes
`faq`	questions and answers
`cta`	a call to action
`hours-location`	address, opening hours and a map link
`trust-bar`	short trust signals, such as "Licensed & insured"
`stats`	two to four figures
`steps`	a process, or what's included, numbered
`split`	an image beside text
`team`	the people, with placeholders until the photos exist
`pricing-list`	prices as the site writes them

The kit's README lists each type's fields, variants and tones.

The site's own section types

For anything the library lacks, a site adds its own section type, such as a restaurant's menu board. It needs three files, changed together:

a component in src/components/sections/site/<type>.astro;
its fields' schema in siteSectionSchemas, in src/site.schema.ts;
its CMS fields under section_types in public/admin/config.site.yml.

Then run npm run decap-config, which assembles the site's CMS config, and npx site-kit schema, which updates the description of the site's content in .hostsmith/schema.json. The build fails while either one is out of date. Commit both files.

Collections

A collection is a folder of Markdown entries, one file per entry, such as the blog in src/content/news/. Each one has:

its fields' schema in siteCollections, in src/site.schema.ts;
a base path in src/site.config.ts, such as /blog, so news/spring-painting-dates.en.md is served at /blog/spring-painting-dates;
a template for an entry's page, in src/components/collections/;
its CMS fields in public/admin/config.site.yml.

A collection-list section shows a collection's entries on any page.

Settings

src/content/settings/site.en.yml holds what isn't specific to one page: the site's name and logo, the navigation, the defaults for search engines, the header's actions, the footer's blocks, facts and interface strings.

The header and footer

The header's actions, such as a phone number and a button, and the footer's blocks, such as contact details, opening hours and links, are listed in the settings like a page's sections. The README lists every action and block.

Facts

A value that appears in several places, such as the phone number, is written once as a fact, and any text uses it by its name:

facts:
  - name: phone
    value: (218) 555-0142
header:
  actions:
    - type: phone
      number: "{phone}"   # quote a YAML value that starts with a brace

Changing the fact changes it everywhere. An unknown name fails the build.

Interface strings

Text that isn't content, such as the menu button's label or a blog post's "Keep reading", is under ui in the settings, so it can be changed and translated like the rest of the content. See interface strings in the README for a site's own.

Media

Photos and other files go in public/assets/, and content names them by their path, such as /assets/images/kitchen.jpg. The build serves them as they are: it doesn't resize or convert images, so size them before adding them. An image's alternative text is a field beside it, such as imageAlt.

Custom pages

A page that needs its own markup sets template: custom, and its markup goes in a page template, src/components/pages/<page>.astro, which can still show the page's sections. basics' about page is one. See custom pages in the README.

What the build checks

Every page, entry and settings file is checked against its schema on every build. The build fails, naming the file and the field, on:

a missing or mistyped field, or one the schema doesn't know;
an unknown section type or fact;
a content file without the site's language in its name;
a CMS config, public/admin/config.yml, that is out of date with the site's schemas.

So a change that builds is a change the site can show. The README has how content works in full.

Hostsmith

Content