How Jivaro Builds Static Websites That Keep Working Without a CMS

The design goal: source once, deploy complete HTML

Jivaro stores each editorial item as structured metadata plus a body-only HTML fragment. A repository-owned Node script combines those sources with shared templates, generates complete static pages, updates every dependent index, and validates the result before publication.

The browser receives ordinary HTML. It does not need a CMS API, database query, or client-side content fetch to display the article.

The source model

content/resources/<slug>/
  article.json
  body.html

content/news/<year>/<slug>/
  article.json
  body.html

article.json owns title, description, dates, taxonomy, hero, FAQ, sources, related links, app relationships, indexing, and legacy URLs. body.html begins at H2 and excludes global page chrome.

Why body-only HTML

A zero-new-dependency system needs a format the browser and generator already understand. HTML fragments avoid importing a Markdown parser or maintaining a partial parser. The tradeoff is strict authoring rules: no full document, H1, global style, script, or generator-managed section in the body.

The deterministic generator

1. Load site data, taxonomy, apps, software, and content.
2. Validate fields, dates, categories, routes, images, and sources.
3. Assign heading IDs and generate TOC.
4. Render article or News layout.
5. Generate FAQ, sources, related reading, app cards, and ads.
6. Generate hubs and category pages.
7. Generate sitemap, search index, feeds, redirects, content graph, and audits.
8. Write complete output into public/.

Running the same build twice without source changes must produce no diff.

Why generated HTML is committed

• GitHub contains the exact website Cloudflare serves.
• Cloudflare installs no publishing framework.
• A failed remote build cannot erase routes.
• Reviewers can inspect final metadata and HTML.
• Rollback is a Git revert.
• A repository archive remains deployable.

Source remains authoritative; generated files are never edited manually.

Shared templates and gradual migration

Templates own the document shell, navigation, metadata, structured data, article layout, TOC, FAQ, sources, related cards, and footer. A static-page normalizer applies shared assets, skip links, image dimensions, safe links, heading repair, catalog state, and planned-offer handling to older pages.

Every index comes from the same graph

Quality control is publishing

npm run verify cleans metadata and retired assets, builds, normalizes static pages, checks routes/assets/metadata/schema/feeds/redirects, and tests catalog layout. It rejects drafts in public output, duplicate IDs, broken TOCs, stale files, competing scroll owners, oversized optimized images, and accidental attachments.

Cloudflare is the host, not the content database

Cloudflare Pages publishes the committed public/ directory. Functions handle approved redirects and affiliate routes. Moving hosts would require adapting headers and Functions, not migrating a content database.

What this system does not provide

• A visual browser editor.
• Multi-user editorial permissions.
• Hosted draft workflows by default.
• Database queries or personalization.
• Automatic editorial judgment.

Jivaro chose a narrower system optimized for portability, deterministic output, and direct control.

The publishing workflow

1. Create a source shell.
2. Write and verify metadata and body.
3. Add hero and optimized variants.
4. Add structured sources, FAQ, and relationships.
5. Set draft false.
6. Run npm run verify.
7. Use publish.ps1 to commit, rebase, rebuild, and push.
8. Wait for Cloudflare and run live QC.

Failure recovery and rollback

The publishing script refuses to push when generation, static QC, layout QC, Git checks, or deterministic rebuild fails. The previous public files remain in Git until a verified commit replaces them. If production is wrong, the operator can revert the commit and let Cloudflare serve the prior generated output.

Live QC then requests canonical routes, alternate-host redirects, legacy redirects, and a build marker. This catches the class of failure where the repository is correct but the host serves an older deployment or different platform.

When Jivaro would adopt a CMS

A CMS becomes attractive when nontechnical authors need visual editing, roles and permissions, workflow states, hosted previews, scheduling, or structured reuse at a scale that exceeds repository review. The migration decision would include export guarantees and a static fallback. Avoiding a CMS is not an ideology; it is the current tradeoff for this team and site.

Frequently asked questions

Related reading

Sources and references

• Cloudflare Pages documentationCloudflare · reference
• GitHub Actions documentationGitHub Docs · reference