Under the hood

How a page gets built

From a markdown file with YAML frontmatter to a validated, rendered, deployable static page - here's the whole pipeline.

Step 1 - Write

Pages are lists of blocks

Every page is a markdown file whose frontmatter declares a blocks array. Each entry has a type plus that block's fields - the full vocabulary is on the blocks page, rendered live.

src/pages/example.md

---
name: Example
permalink: /example/
blocks:
  - type: hero
    content: |
      # Hello
  - type: markdown
    content: Body text here.
---

Step 2 - Validate

The build checks every block

Unknown block types and unknown keys fail the build with an error naming the file and the block - typos never reach production. The same schemas generate the editor config and the reference docs, so none of them can drift apart.

terminal

[11ty] Block type "herro" is unknown
(block 1 in ./src/pages/example.md).
Valid types: section-header, features,
image-cards, stats, code-block, hero, ...

Step 3 - Build

One command, one directory

Eleventy renders every page, processes images into responsive formats, bundles CSS and JS, builds the search index, and checks every internal link. The result is a plain _site/ directory.

terminal

npm run build
# -> _site/
#    index.html, blocks/, guide/, news/ ...
#    css/, assets/, images/, pagefind/

Step 4 - Deploy

Push to deploy

A GitHub Actions workflow builds and publishes the site to GitHub Pages on every push to main - project subpaths and custom domains both work without editing anything. _site/ is also uploaded as a build artifact, so any other static host can serve it instead.

.github/workflows/pages.yml

- name: Build Site
  env:
    PATH_PREFIX: $/
    SITE_URL: $
  run: npm run build