Fourfold

Fourfold is an Astro theme for building a static-first personal publication site that organizes writing, columns, projects, research, and photo essays through a content-model-driven architecture rather than a flat article list. The template, published under the Liyuk/astro-fourfold repository with a v0.1.0 release, accepts Markdown and MDX files in six validated content collections and outputs a fully static site with HTML pages, an RSS feed, sitemap, dynamic robots.txt, Open Graph metadata, BlogPosting JSON-LD, and a client-side search index.

What is Fourfold?

Fourfold is a personal publication theme for Astro that treats content as structured collections instead of a single blog feed. It takes Markdown/MDX content from src/content/ — writing, columns, projects, research, photos, and links — validates each file's frontmatter against a schema at build time, and generates static pages with year-month URLs, yearly archives, and aggregation views. The default site language is Chinese, with locale and translationKey fields reserved for future English mirror pages. It runs on Astro and can be deployed to GitHub Pages, Cloudflare Pages, Netlify, Vercel Static, or any static CDN.

What makes Fourfold stand out?

• Writing archive — Markdown/MDX articles get year-month URLs, yearly archives, featured and recent-updated sorting, plus previous/next article links.
• Long-form reading tools — auto table of contents, excerpts, reading time, tags, related articles, and a copy-link button are included on article pages.
• Columns versus tags — columns group articles into an ordered reading sequence using a column name and order field, while tags are auto-generated from frontmatter into index pages.
• Project and research records — projects carry active/maintained/paused/archived status plus a project type; research notes support note/preprint types, version numbers, and code/paper link slots.
• Photo galleries — a curated gallery index and individual gallery detail pages are implemented as a dedicated content collection.
• Backend-free search — /search-index.json is generated at build time; the search page matches titles, summaries, body text, and tags and syncs the query into the ?q= parameter.
• Local favorites — readers can save article URLs to localStorage without an account, and no data is uploaded anywhere.
• Content validation — npm run validate:content catches missing required fields, duplicate translationKeys, duplicate article URLs, invalid columns, and broken resource references.

Who is Fourfold for?

• Independent writers who want a publication-style site with columns for serialized reading, featured articles, and a distinct archive beyond a chronological feed.
• Researchers and academics who need to publish notes and preprints with version numbers, tags, and external code or paper links alongside their writing.
• Photographers and designers who want to combine photo essays and project status pages with a writing archive under one consistent navigation.
• Astro developers who want a typed content schema, a documented architecture, and a CI workflow for GitHub Pages.

What can you do with Fourfold?

• Run a no-backend personal site: deploy static HTML where search uses a build-time JSON index and favorites live in the browser, so there is no database or account system to maintain.
• Publish a themed reading series: wire articles to a column with a columnOrder value so readers can follow a recommended path, while tags handle cross-topic discovery.
• Maintain a project portfolio: track each project's status (active, maintained, paused, archived) and type on dedicated project pages.
• Ship to GitHub Pages automatically: the repository includes a deploy workflow that computes SITE_URL and BASE_PATH from the actual repository, so you don't edit your username into the source.

Pros and cons

• Pro: The template ships with a complete publishing pipeline — RSS, sitemap, Open Graph, JSON-LD, dynamic robots, and a custom 404 — so basic SEO infrastructure is handled out of the box.
• Con: The core site is intentionally lightweight: no commenting, email subscription, cloud favorites sync, or analytics are bundled, keeping the layout vendor-neutral but requiring you to integrate services like Giscus, Buttondown, Plausible, or Umami yourself.
• Con: The built-in search is a basic in-browser matcher that is a good fit for small to medium archives; the README recommends migrating to Pagefind or MiniSearch once content reaches the hundreds or thousands of articles.
• Con: The template ships with Chinese as the default UI language and Chinese placeholder content; English fields exist in the schema, but full English mirror pages are not generated until real translations are added.

FAQ

Does Fourfold require a backend?

No. The site is fully static: Astro pre-renders all pages as HTML, search reads a build-generated /search-index.json file, and favorites are stored in the reader's localStorage. Optional features such as comments, email subscription, or analytics require third-party services that you add yourself.

Which frontmatter fields are required for a writing article?

Writing articles need title, description, locale, publishedAt, and author. Optional fields include updatedAt, translationKey, featured, minutes, column, columnOrder, and draft. Draft articles are excluded from public lists, RSS, and sitemap.

How do I deploy Fourfold to GitHub Pages?

Copy .env.example to .env, set SITE_URL to your domain, and configure BASE_PATH as / for a user site or the repository name for a project site. The included GitHub Actions workflow derives these values from the actual repository context, so you don't hardcode your GitHub username in the template source.

Does Fourfold support multiple languages?

The schema includes locale and translationKey fields, and the recommended approach is parallel files such as hello-world.zh-cn.md and hello-world.en.md in the writing collection. The template currently defaults to Chinese, with English fields reserved but not yet rendered as full mirror pages.

How do I run content validation?

Run npm run validate:content to check required fields, duplicate translationKeys, duplicate article URLs, invalid column references, and broken resource references. Run npm run check after adding content to ensure the build passes before deploying.