al-folio Documentation

These guides cover the al-folio v1.x starter and its pluginized runtime.

User Guides

• Quick Start: create a site from the template and get it live quickly.
• Installing and Deploying: Docker, local setup, GitHub Pages, Netlify, and upgrade guidance.
• Customizing: content, CVs, publications, layouts, local overrides, and feature configuration.
• FAQ: common deployment, upgrade, plugin, and troubleshooting questions.
• Troubleshooting: build, deployment, styling, and content debugging.
• Analytics: analytics provider setup.
• SEO: search-engine and social preview setup.

Maintainer Guides

• Architecture: how the starter and its plugin gems fit together, the failure modes that produce no error message, the v1 config contract, and local overrides.
• Ownership Boundaries: starter-vs-plugin ownership, PR routing, and release responsibilities.
• Contributing: contributor workflow, validation, and agent guidance.
• Bootstrap skill: agent workflow for new v1 sites.
• Migration skill: agent workflow for customized fork migrations and override audits.

v1 Plugin System

al-folio v1.x is a thin starter. It owns site wiring, example content, documentation, integration tests, and visual tests. Runtime behavior belongs in Ruby gems maintained under the al-org-dev organization. See Architecture for how the two halves connect, and AGENTS.md if you are a coding agent.

When changing feature behavior, route the work to the owning plugin repo first. Update this starter only when the change affects:

• Gemfile dependency pins,
• _config.yml plugin activation or feature flags,
• _data/featured_plugins.yml catalog metadata (rendered as the plugin catalog page, source _pages/plugins.md),
• documentation, examples, integration tests, or visual parity coverage.

See Ownership Boundaries for the full routing table.