What Lives in website/
The public site lives under website/. The main directories and configuration files are:
website/
config/_default/
content/
docs/
filestash-alternative/
data/
docs-nav/
docs-versions.toml
filestash_alternative.yaml
homepage.yaml
managed-redirects.toml
scripts/
tests/
themes/sambee/
assets/
static/
In practice:
config/_default/holds site parameters (params.toml), menus, and Hugo module mounts.content/holds authored website pages (including standalone legal pages and comparison page bundles) and docs pages.content/docs/holds the published versioned docs books.data/holds structured YAML content for the homepage and comparison pages (homepage.yaml,filestash_alternative.yaml),docs-versions.toml,docs-nav/<version>.toml, andmanaged-redirects.toml.scripts/holds build helpers, docs validation, docs materialization, homepage and marketing CTA validation, media generation, and docs editor automation.tests/holds Pythonunittestsuites for docs routing, docs validation, managed redirects, docs reports, and built marketing pages.themes/sambee/holds the Hugo layouts, partials, CSS, and JavaScript for the public site.assets/andstatic/hold source media, generated WebP and social-card derivatives, and static files.
Site Page Families
sambee.net separates templates and stylesheets into three page families that share brand tokens, layout rails (.ledger-shell and .shell-section in shared.css), global header and footer chrome, and type-* typography utilities without cloning section layouts across page types:
- Homepage (
/): Useslayouts/home.html,partials/home/*,assets/css/homepage.css, anddata/homepage.yaml. These section partials are exclusive to/. - Comparison and marketing pages (
/<slug>/): Use a page bundle atcontent/<slug>/index.md(layout = "comparison",data_key = "<key>") backed by structured data indata/<key>.yaml, rendered throughlayouts/_default/comparison.html,partials/marketing/*, andassets/css/marketing.cssinside the shared.ledger-shell/.shell-sectionmain content container. Comparison pages emitFAQPageJSON-LD through the{{ block "head" . }}slot inlayouts/_default/baseof.html, exposedata-pagefind-bodyunderpage_kind:site, surface in the footer via[[footer.comparisons]]inconfig/_default/params.toml, and mark CTAs and subnav jump links withdata-marketing-linkfor build-time validation. - Documentation and standalone prose pages (
/docs/...,/imprint/,/privacy-policy/): Versioned docs uselayouts/docs/*andassets/css/docs.css; single-column legal and reference pages outside/docs/uselayouts/_default/standalone.htmlandassets/css/standalone.css.
Shared link and media helpers live in partials/components/ (including link-href.html, button-kind-class.html, responsive-image.html, and theme-aware-image.html), and shared layout and typography utilities live in assets/css/shared.css.
How Docs Routing Works
Docs content is versioned in the content tree:
website/content/docs/<version>/<book>/<section>/<page>/index.md
The current docs version also publishes stable unversioned routes:
/docs/<book>//docs/<book>/<section>//docs/<book>/<section>/<page>/
Archived or explicit versioned routes remain available at:
/docs/<version>//docs/<version>/<book>/...
The routing rules, inheritance markers, and stable-current behavior are covered in more detail in Docs Content Model, Navigation, and Inheritance .
Build and Preview Pipeline
The website build runs an ordered validation and asset pipeline rather than a plain Hugo render.
Run a production-style build from website/:
cd website
npm run build
That command runs:
- Theme CSS generation (
scripts/themeGenerator.js). - Docs navigation and content validation (
scripts/validate-docs-content.py). - Inherited-doc route materialization (
scripts/materialize-inherited-docs.py). - Hugo production site build (
hugo --minify). - Manifest-based HTTP redirect generation and validation (
scripts/generate-managed-redirects.py). - Pagefind search indexing (
npx pagefind). - Homepage and marketing CTA validation (
scripts/validate-homepage-ctas.py) plus docs output validation (scripts/validate-docs-output.py).
build:deploy and build:search run the same pipeline. HUGO_BASEURL sets the base URL. Deploy HTML, docs-routes.json, and _redirects from a single build.
Run the website Python test suite from the repository root:
python3 -m unittest discover -s website/tests
For local development, run:
./scripts/start-website
Or run the website development workflow directly:
cd website
npm run dev
Use the Website: Start Dev Server VS Code task for local checks. The development pipeline writes to website/public-dev/, separate from production output in website/public/. The authoring loop updates inherited anchors and WebP assets automatically.
Normal startup validates source docs, renders Hugo, generates redirects, and checks homepage and marketing links. It skips minification, garbage collection, search indexing, and full docs output validation.
- Use
npm run dev:with-searchfor an initial search index and continuous index updates. - Use
npm run dev:searchfor a one-time development build and search index. After further edits, that index can be stale. - Use
npm run dev:checkfor the complete development build, including search indexing and output validation.
Normal preparation removes any old local search index so it cannot return stale results. The search dialog explains how to enable local search. Development indexing defaults to four worker threads; set RAYON_NUM_THREADS to use a different limit. Production builds keep the full validation pipeline and do not set a thread limit.