Webifier User Guide

Webifier is built around a small idea: publishing should feel close to writing and committing files. You keep Markdown, notebooks, HTML files, PDFs, reports, and assets in Git. Webifier reads the page structure you describe and turns the reachable files into a static website.

This guide is also a working example. The pages are ordinary Markdown and YAML files, and the website you are reading is generated from them.

The important design point is that Webifier itself is intentionally small. Extensions teach it what page syntax means. When you enable the standard extension, keys like header, nav, meta, and footer become page controls. When you enable Markdown, notebooks, PDFs, comments, people cards, or a custom extension, those extensions add their own renderers, page config, hooks, templates, assets, and sometimes their own page-level keys.

So the mental model is:

• Start with one page, usually index.yml.
• Enable the extensions that define the grammar you want to use.
• Write visible sections as ordinary YAML keys in reading order.
• Put behavior under config.
• Link to Markdown, notebooks, PDFs, YAML pages, and assets.
• Let Webifier follow those links and render the static site.

These pages are the shortest path from an empty repository to a working Webifier site. Read them in order if you are setting up a project for the first time; each page starts with the idea and ends with the detailed syntax.

• Hello World Website: create the smallest useful Webifier page from one YAML file.
• Installation and GitHub Actions: install the packages, render locally, and add a GitHub Actions workflow.
• YAML Pages and Sections: learn the top-to-bottom page model with rendered examples.
• Section Controls: add labels, templates, defaults, and renderer dispatch.
• Links and Page Discovery: link Markdown, notebooks, YAML pages, and static assets.

Use these pages once the first tutorial path makes sense. They explain the default site grammar, content files, and the config layer you will edit most often.

• Using the Default Site: understand how enabling webifier.standard gives you the default page grammar.
• Render and Automate: run the build locally and wire it into repository publishing.
• Navigation and Pages: configure site navigation and decide which pages belong in the guide.
• Publishing Content Files: publish Markdown, notebooks, HTML, PDFs, and assets from your repository.
• Configuration Basics: keep site-level defaults, page settings, and extension options in one place.

Extensions are where Webifier becomes reusable. The first-party extension pages show the available building blocks. The customization pages then show how to override templates, add renderers, and package repeatable site formats.

• Extensions Overview: lifecycle, named instances, hooks, page config, and consumed page keys.
• Bundled Extensions: standard pages, Markdown, notebooks, PDFs, chapters, people, resume, theme, comments, search, and analytics.
• Themes and Styles: set defaults, switch themes, and prepare for custom visual systems.
• Template Overrides: replace specific templates without rewriting the whole site.
• Template-Only Renderers: add new rendering kinds from templates alone.
• Python Renderers and Resolvers: plug in Python code when templates are not enough.
• Custom Extensions and Reusable Formats: install custom extensions, update GitHub Actions, and package repeatable formats.
• Renderer / Kind System: use this reference when you need the lower-level dispatch model.

Use the reference pages when you need exact syntax, lifecycle details, or a deeper mental model for extending Webifier. These pages are intentionally more complete than the tutorials.

• Architecture Overview: see the core pieces and how extensions fit around them.
• YAML Syntax Specification: check the supported YAML shapes and reserved keys.
• Resolver System: understand how links, files, and generated pages are discovered.
• Renderer / Kind System: map kind, templates, and renderer dispatch.
• Extension and Customization Guide: write extensions that register renderers, hooks, templates, and assets.
• Processing Pipeline: follow the build lifecycle from config loading to output files.