Clarify extension-driven docs workflow

Author: vahidzee

configurations/config.yml

@@ -4,10 +4,19 @@ webifier:
       uses: webifier.standard
     markdown:
       uses: webifier.markdown
+      toc: true
+      cleanup: false
     notebook:
       uses: webifier.notebook
+      toc: true
+      cleanup: true
+      colab: true
     pdf:
       uses: webifier.pdf
+      toc: false
+      download: true
+      toolbar: true
+      height: min(82vh, 1100px)
     theme:
       uses: webifier.theme
       switcher: true
@@ -47,6 +56,8 @@ page_navigation:
       items:
         - title: User Guide
           href: /pages/user-guide/
+        - title: Hello World Website
+          href: /pages/user-guide/tutorials/00-hello-world.html
         - title: Installation and GitHub Actions
           href: /pages/user-guide/tutorials/00-installation-and-github-actions.html
         - title: YAML Pages and Sections
@@ -101,7 +112,7 @@ page_navigation:
           href: /pages/user-guide/08-template-renderers.html
         - title: Python Renderers and Resolvers
           href: /pages/user-guide/09-python-renderers-and-resolvers.html
-        - title: Reusable Website Formats
+        - title: Custom Extensions and Reusable Formats
           href: /pages/user-guide/10-reusable-formats.html
     - title: Reference
       items:

pages/user-guide/01-default-site.md

@@ -7,9 +7,20 @@ header:
 
 # Using the Default Site
 
-The fastest way to use Webifier is to let the default renderer do the work. You
-create an `index.yml`, point it at content, and let Webifier build the page,
-copy assets, and generate linked content pages.
+The fastest way to use Webifier is to enable the bundled extensions and let the
+default renderers do the work. You create an `index.yml`, point it at content,
+and let Webifier build the page, copy assets, and generate linked content pages.
+
+Webifier core does not try to own a giant website syntax. The syntax becomes
+useful when extensions are enabled. In the default setup:
+
+| Extension | What it teaches Webifier |
+|---|---|
+| `webifier.standard` | Page controls such as `header`, `nav`, `meta`, `footer`, sections, links, and the base page shell |
+| `webifier.markdown` | Markdown blocks and linked Markdown pages |
+| `webifier.notebook` | Linked notebook pages and notebook page config |
+| `webifier.pdf` | Linked PDF pages with site navigation and optional controls |
+| `webifier.theme` | Light/dark/system theme behavior |
 
 For the first-principles version of this idea, start with
 [YAML Pages and Sections](index=pages/user-guide/tutorials/01-yaml-pages-and-sections.yml).
@@ -28,6 +39,8 @@ config:
         uses: webifier.markdown
       notebook:
         uses: webifier.notebook
+      pdf:
+        uses: webifier.pdf
 
 header:
   title: My Project
@@ -45,21 +58,55 @@ docs:
   body: |
     - [Project Notes](md=pages/notes.md)
     - [Experiment Notebook](md=pages/experiment.ipynb)
+    - [Final Report](pdf=reports/final.pdf)
 ```
 
-The root YAML file becomes the home page. Each top-level key after `title`,
-`header`, `nav`, `meta`, and `config` becomes a section rendered by the default
-section renderer.
+The root YAML file becomes the home page. With `webifier.standard` enabled,
+page-level keys such as `title`, `header`, `nav`, `footer`, `meta`, `style`, and
+`config` are controls. Other top-level keys become sections rendered in source
+order.
+
+That distinction is extension-defined. A custom extension can claim another
+page key, consume it, and remove it before section rendering. If no extension
+claims a key, the standard renderer treats it as content.
 
 ## What You Get By Default
 
 - A homepage assembled from YAML sections
 - Markdown rendering for text blocks
 - Generated pages for linked Markdown and notebook files
+- Embedded PDF pages when the PDF extension is enabled
 - Asset copying for local images and files
 - Search index generation
 - Navigation, comments, analytics, and theme support when configured
 
+## The Default Contract
+
+Use this split when you are deciding where something belongs:
+
+| Put it here | When |
+|---|---|
+| `config.webifier.extensions` | You are enabling or configuring site behavior |
+| `config.<instance-name>` | You are overriding one extension for one page |
+| reserved page keys | You are changing page chrome, such as title, header, nav, or footer |
+| ordinary page keys | You are adding visible sections |
+| linked content files | You already have Markdown, notebooks, PDFs, HTML, or assets in the repo |
+
+For example:
+
+```yaml
+config:
+  markdown:
+    toc: false
+
+summary:
+  label: Summary
+  content: This is visible.
+```
+
+`config.markdown` changes Markdown behavior for this page. `summary` renders as
+content.
+
 ## When To Stay With Defaults
 
 Stay with the default renderer when the goal is to publish clearly, not design a

pages/user-guide/02-render-and-automate.md

@@ -19,6 +19,14 @@ Install Webifier in the Python environment you use for the project:
 pip install webifier
 ```
 
+Installing `webifier` also installs the first-party extension package. If your
+site uses third-party or project-specific extensions, install those into the
+same environment:
+
+```shell
+pip install webifier my-webifier-extension
+```
+
 From the repository root, run:
 
 ```shell
@@ -41,6 +49,28 @@ python -m http.server 4173 --directory webified
 
 Then open `http://localhost:4173/`.
 
+## Extension Dependencies
+
+Webifier is extension-dependent by design. Your root page config declares which
+extension instances are active:
+
+```yaml
+config:
+  webifier:
+    extensions:
+      site:
+        uses: webifier.standard
+      markdown:
+        uses: webifier.markdown
+      related_posts:
+        uses: my.related_posts
+        source: posts/
+```
+
+That config is enough only if the Python package providing `my.related_posts`
+is installed. Local builds, GitHub Actions, and any other build environment
+need the same packages available before `webify` runs.
+
 ## Automate With GitHub Actions
 
 Add a workflow such as `.github/workflows/webifier.yml`:
@@ -64,12 +94,14 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Webify
-        uses: webifier/build@v1.0.1
+        uses: webifier/build@v1.0.5
         with:
           baseurl: ''
           index: index.yml
           publish_dir: webified
           templates_dir: .
+          # Optional: install custom extension packages before rendering.
+          # extra-packages: my-webifier-extension
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
@@ -82,6 +114,28 @@ If your site is published under a project path such as
 `https://username.github.io/project-name/`, set `--baseurl '/project-name'`
 instead of `''`.
 
+For a custom extension package from GitHub:
+
+```yaml
+extra-packages: "my-webifier-extension @ git+https://github.com/me/my-webifier-extension.git"
+```
+
+For more than one package, use a YAML block with one requirement per line:
+
+```yaml
+extra-packages: |
+  my-webifier-extension
+  another-extension
+```
+
+If you call `webify` directly instead of using the action, add the extension to
+the install step:
+
+```yaml
+- name: Install Webifier and extensions
+  run: pip install webifier my-webifier-extension
+```
+
 ## What Automation Gives You
 
 Git tracks the source content. GitHub Actions notices a push. Webifier renders
@@ -95,4 +149,14 @@ project:
 3. Push to GitHub.
 4. Let the action rebuild the website.
 
+## Summary
+
+| Where | What to remember |
+|---|---|
+| `pip install webifier` | Installs core Webifier and first-party extensions. |
+| custom extensions | Install them wherever `webify` runs. |
+| `config.webifier.extensions` | Declares the extension instances the site uses. |
+| Webifier action | Use `extra-packages` for third-party or project-specific extensions. |
+| direct CLI workflow | Install custom packages before calling `webify`. |
+
 Next: [Navigation and Pages](03-navigation-and-pages.html).

pages/user-guide/03-navigation-and-pages.md

@@ -39,6 +39,70 @@ content:
 The brand link usually takes people home, so you do not need a separate Home
 item unless your site wants one.
 
+## Bottom Page Navigation
+
+The standard page templates can also render a bottom previous/home/next block.
+This is useful for documentation, tutorials, course notes, and any content that
+has a preferred reading order.
+
+Set the default sequence in site config:
+
+```yaml
+config:
+  page_navigation:
+    home:
+      title: User Guide
+      href: /pages/user-guide/
+    items:
+      - title: Start
+        href: /pages/user-guide/
+      - title: Installation
+        src: pages/user-guide/tutorials/00-installation-and-github-actions.yml
+      - title: YAML Pages
+        src: pages/user-guide/tutorials/01-yaml-pages-and-sections.yml
+      - title: Section Controls
+        src: pages/user-guide/tutorials/02-section-controls.yml
+```
+
+`items` can be nested for organization. Webifier flattens the readable entries,
+matches the current page by `href` or `src`, then renders the previous and next
+neighbors. `src` entries are resolved to the generated `.html` URL, which keeps
+the config close to the source files.
+
+Each page can override or hide this block from its own `config`:
+
+```markdown
+---
+title: One-off Page
+config:
+  page_navigation: false
+---
+```
+
+Or override individual slots:
+
+```yaml
+config:
+  page_navigation:
+    previous: false
+    home:
+      title: Docs
+      href: /pages/user-guide/
+    next:
+      title: Extension Overview
+      href: /pages/user-guide/extensions/
+```
+
+Slot values can be:
+
+- `false`: hide that slot.
+- a string: use it as the link URL.
+- an object with `title` or `text` plus `href`, `link`, or `src`.
+
+Page-local navigation config is merged over the site-level sequence for that
+page only. Linked child pages use the site default unless they define their own
+page config.
+
 ## Generated Content Pages
 
 Use `md=...` links when you want Webifier to render a source file as a page:

pages/user-guide/04-content-files.md

@@ -20,7 +20,7 @@ Link to a Markdown file with `md=...` to generate a page:
 [Read the notes](md=pages/notes.md)
 ```
 
-Markdown front matter can provide page metadata:
+Markdown page prefaces can provide the same page data as YAML pages:
 
 ```markdown
 ---
@@ -33,7 +33,7 @@ header:
 # Notes
 ```
 
-Front matter can set page controls such as `title`, `header`, `nav`, `footer`,
+The page preface can set page controls such as `title`, `header`, `nav`, `footer`,
 `meta`, `style`, and page-local `config`.
 
 ## Notebooks
@@ -48,7 +48,7 @@ This makes Webifier a good fit for research projects, experiments, and small
 technical reports where the notebook is the work and the website is the sharing
 surface.
 
-Notebook pages can use the same page metadata shape in the first Markdown cell:
+Notebook pages can use the same page-data shape in the first Markdown cell:
 
 ```markdown
 ---
@@ -75,11 +75,11 @@ site-styled frame:
 [Read the report](pdf=reports/index.pdf)
 ```
 
-Put `metadata.yml` beside the PDF to control the generated page title:
+Put `page.yml` beside the PDF to control the generated page title:
 
 ```yaml
 title: Final Report
-metadata:
+meta:
   description: Embedded PDF report.
 ```