unaltraweb 0.3.0

data/docs/_documentation/en/06-github-web-editing.md

@@ -0,0 +1,92 @@
+---
+title: Edit Safely In GitHub Web
+description: A browser-only content workflow that prevents overlapping edits and lost work.
+lang: en
+ref: github_web_editing
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+section: Start Here
+weight: 20
+permalink: "/github-web-editing/"
+nav_title: GitHub Web Editing
+---
+<p class="lede">GitHub Web is a supported path for small content updates. Editors coordinate through issues, one-task branches, and Draft pull requests; maintainers own local rendering, merge decisions, and manual deployment.</p>
+
+## Before Editing
+
+1. Open or choose an issue describing one focused task.
+2. Be assigned to it, or post an explicit reservation naming every file you intend to edit and wait for maintainer acceptance.
+3. Check the issue and open pull requests before starting. There must be only one active editor per file.
+4. Create one branch for the task. Never edit or commit directly to `main`.
+5. Open a Draft pull request early, link the issue, and list the reserved files.
+
+An issue without an assignee or accepted reservation is not a claim on files. A broad reservation such as "all chapters" should be split into smaller tasks before editing begins.
+
+## While Editing
+
+- Change only reserved files and keep the pull request small enough to review as one task.
+- Use a separate issue and branch for unrelated corrections, reorganizations, or formatting.
+- Recheck the pull request's **Files changed** tab before requesting review.
+- Keep the pull request in Draft while files or content are incomplete.
+- If GitHub reports a conflict or another editor needs the same file, stop. Do not choose "accept ours/theirs", recreate the file, or overwrite their work. Ask the maintainer to sequence or reconcile the tasks.
+
+This protocol makes overlap visible before work is lost. Chat messages may help coordination, but the issue or reservation and Draft pull request are the repository record.
+
+## Choose The Right Content Paths
+
+The generated site's `README.md` identifies its selected profile and gives the authoritative editor list. Typical paths are:
+
+| Profile | Purpose | Typical editable content |
+|---|---|---|
+| `unaltreselfie` | Personal academic or professional site | `_pages/<lang>/`, `_posts/`, `_news/`, `_projects/`, `_books/`, `_bibliography/`, approved profile images and CV files |
+| `unaltreprojecte` | Research project, group, infrastructure, or output site | `_pages/<lang>/`, `_news/`, `_projects/`, `_outputs/`, `_books/`, `_data/team.yml`, `_data/repositories.yml`, `_bibliography/`, approved project images |
+| `unaltremanual` | Manual, course, handbook, or book-like publication | `_pages/<lang>/`, `_chapters/<lang>/`, `_bibliography/`, `context/writing-profile.md`, approved source images |
+| `unaltredocs` | Technical or operational documentation | `_pages/<lang>/`, `_documentation/<lang>/`, public `_data/` files, approved screenshots |
+
+A small change to public title, URL, languages, or profile options in `_config.yml` requires maintainer agreement. Do not restructure configuration in a content pull request.
+
+## Upload Images Safely
+
+1. Reserve the new filename and upload it on the task branch, not on `main`.
+2. Put it in `assets/img/` or an established editorial image subfolder. Never upload into `assets/img/generated/`.
+3. Use a descriptive lowercase filename and prefer a reasonably sized PNG, JPEG, or WebP. Only use SVG from a reviewed, trusted source.
+4. Confirm publication rights and check that the file contains no confidential information, unintended personal data, or sensitive metadata.
+5. Prefer a new filename. Replace an existing file only when that exact replacement was reserved.
+6. Reference the image in the same pull request and add meaningful alternative text. The maintainer must inspect the rendered page.
+
+## Never Edit These In GitHub Web
+
+- `.github/`, `.unaltraweb/`, `.gitignore`, `Gemfile`, `Gemfile.lock`, and `Makefile` control repository or runtime behaviour.
+- `_layouts/`, `_includes/`, `_plugins/`, and `_sass/` are technical theme overrides.
+- `_site/`, `tmp/`, `.jekyll-cache/`, `.bundle/`, and `vendor/` are build products or caches.
+- `assets/img/generated/`, `.unaltraweb/computations.lock.json`, `.vegavisuals.lock.json`, rendered diagrams/captures, and files marked as generated belong to local renderers.
+- A generated `.md` owned by a `.qmd`, `.Rmd`, `.R`, `.py`, or `.ipynb` source must not be hand-edited. A maintainer edits and renders the source locally.
+- The default manual outputs `assets/pdf/manual-<lang>.pdf` and `assets/img/manual-cover-<lang>.png` are deployment products, not versioned source files.
+
+Never put passwords, access tokens, API keys, private keys, credentials, or `.env` files in issues, commits, branches, or pull requests. Ask the maintainer about any path not explicitly listed as editable.
+
+## Maintainer Handoff
+
+After the editor requests review, the maintainer:
+
+1. Verifies the issue assignment or reservation, task branch, and changed-file scope.
+2. Checks out the branch locally and runs the site checks plus every required computation, diagram, visualization, capture, and PDF render.
+3. Reviews the rendered web output and, for a manual, the PDF and cover.
+4. Resolves any overlap or conflict with the affected editors, then approves and merges the small pull request.
+5. Starts deployment manually only after the reviewed change is on `main` and publication is intended.
+
+Pushing a branch or merging to `main` does not publish a generated site. Local checks and renders do not deploy it either.
+
+## unaltremanual Publishing
+
+- `latest` is a manual-only deployment from the reviewed `main` branch.
+- A push or merge to `main` does not deploy it. The maintainer runs local checks/renders and then starts the deploy workflow manually.
+- When PDF output is enabled, `assets/pdf/manual-<lang>.pdf` and `assets/img/manual-cover-<lang>.png` are generated during deployment and are not versioned. Existing tracked copies need one reviewed `git rm --cached` migration by a maintainer.
+- Stable editions use `vYYYY.MM(.N)`: `vYYYY.MM` for the first edition in a month and `vYYYY.MM.N` for an additional edition. They are deferred to explicit releases, and deploying `latest` does not create one.
+- The release selector and channel are visible in the generated manual home, `manual-release.json`, and PDF editorial metadata.
+- Release checks reject `legacy/` or `sandbox/` material if it appears in the generated site. Keep it outside current manual content paths.

data/docs/_documentation/en/10-profiles.md

@@ -0,0 +1,125 @@
+---
+title: Choose A Site Profile
+description: Prepared website families supported by unaltraweb.
+lang: en
+ref: site_profiles
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Build A Site
+weight: 220
+permalink: "/profiles/"
+nav_title: Site Profiles
+---
+<p class="lede">A site profile is a high-level prepared website family. It is not a Jekyll layout or include. Profiles select the real build shape before Jekyll writes the site.</p>
+
+```yaml
+unaltraweb:
+  site_profile: unaltreselfie
+  features:
+    blog: true
+    cv: true
+    projects: true
+    publications: true
+    metrics: true
+```
+
+## Current Profiles
+
+- **unaltreselfie**: academic or professional personal sites with profile home, optional blog, CV, projects, publications, readings, social links and content search.
+- **unaltreprojecte**: research project sites with home pages, team, outputs, publications, resources, repositories, news and content search.
+- **unaltremanual**: book-like manuals with localized chapters, sidebar navigation, right-hand table of contents, manual search and teaching blocks.
+- **unaltredocs**: technical documentation sites with left-hand index, search, reusable examples and operational pages.
+
+## Screenshots
+
+These screenshots come from the companion template render smoke tests and are generated from working profile builds.
+
+<div class="row g-4">
+  <div class="col-md-6">
+  <figure class="figure">
+    <img class="figure-img img-fluid rounded border" src="https://raw.githubusercontent.com/dosquartsdedocs/unaltraweb-template/main/assets/img/screenshots/home-light-chromium.png" alt="unaltreselfie profile home page screenshot" loading="lazy">
+    <figcaption class="figure-caption"><strong>unaltreselfie.</strong> Personal academic homepage with profile card, highlights, posts, publications and projects.</figcaption>
+  </figure>
+  </div>
+  <div class="col-md-6">
+  <figure class="figure">
+    <img class="figure-img img-fluid rounded border" src="https://raw.githubusercontent.com/dosquartsdedocs/unaltraweb-template/main/assets/img/screenshots/project-home-chromium.png" alt="unaltreprojecte profile home page screenshot" loading="lazy">
+    <figcaption class="figure-caption"><strong>unaltreprojecte.</strong> Research project homepage with project navigation, team, outputs and resources.</figcaption>
+  </figure>
+  </div>
+  <div class="col-md-6">
+  <figure class="figure">
+    <img class="figure-img img-fluid rounded border" src="https://raw.githubusercontent.com/dosquartsdedocs/unaltraweb-template/main/assets/img/screenshots/manual-home-chromium.png" alt="unaltremanual profile home page screenshot" loading="lazy">
+    <figcaption class="figure-caption"><strong>unaltremanual.</strong> Course/manual home with chapters, teaching affordances and reader-oriented layout.</figcaption>
+  </figure>
+  </div>
+  <div class="col-md-6">
+  <figure class="figure">
+    <img class="figure-img img-fluid rounded border" src="https://raw.githubusercontent.com/dosquartsdedocs/unaltraweb-template/main/assets/img/screenshots/unaltredocs-home-chromium.png" alt="unaltredocs profile home page screenshot" loading="lazy">
+    <figcaption class="figure-caption"><strong>unaltredocs.</strong> Documentation profile with sectioned content and documentation navigation.</figcaption>
+  </figure>
+  </div>
+</div>
+
+## Choosing A Profile
+
+| Profile | Use it for | Main content |
+|---|---|---|
+| `unaltreselfie` | A person, researcher, lab member or professional portfolio | `author` config, `_posts/`, `_news/`, `_projects/`, `_bibliography/`, CV PDF |
+| `unaltreprojecte` | A research project, funded initiative or group output site | project pages, team data, outputs, repositories, readings, publications and news |
+| `unaltremanual` | A manual, course, handbook or book-like learning resource | `_chapters/`, manual bibliography, callouts, figures, tables, Mermaid diagrams and search index |
+| `unaltredocs` | Technical or operational documentation | `_documentation/` pages with `section`, `subsection` and `weight` front matter |
+
+All four profiles emit `assets/js/content-search-index.json`. The header search returns each whole-word occurrence separately, folds diacritics for matching, and adds previous/next occurrence navigation after a result is opened. Set `search_exclude: true` in front matter for a public page or document that should not enter this index. `search_enabled` controls the separate Ninja Keys title/navigation palette and does not disable content search.
+
+## Local Profile Review
+
+Preview one profile without changing `_config.yml`:
+
+```bash
+make serve SITE_PROFILE=unaltreprojecte
+```
+
+Run all template profile demos together:
+
+```bash
+make serve-allprofiles
+```
+
+The local port convention is:
+
+- `4001`: `unaltreselfie`.
+- `4002`: `unaltreprojecte`.
+- `4003`: `unaltremanual`.
+- `4004`: `unaltredocs`.
+
+## Filtering Content
+
+Pages and documents can opt into profiles:
+
+```yaml
+profiles: [unaltreselfie, unaltreprojecte]
+```
+
+The core filters non-matching pages before writing the site. Alternate profiles should be tested by rebuilding with a config overlay, not by client-side preview switches.
+
+## Feature Flags
+
+Navigation pages can use a feature key:
+
+```yaml
+feature: projects
+nav: true
+```
+
+If `unaltraweb.features.projects` is `false`, the page is hidden from navigation while the content can remain in the repository.
+
+## Documentation Site Name
+
+The public documentation site for this project is called `unaltraweb`. It may use documentation-oriented layouts and examples, but it should present the whole platform rather than brand itself as `unaltredocs`.

data/docs/_documentation/en/11-unaltreselfie.md

@@ -0,0 +1,39 @@
+---
+title: Build A Personal Site With unaltreselfie
+description: Personal academic and professional sites.
+lang: en
+ref: profile_unaltreselfie
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+section: Build A Site
+weight: 230
+permalink: "/profiles/unaltreselfie/"
+nav_title: Personal Site
+---
+Use `unaltreselfie` for a personal academic, researcher or professional website.
+
+```yaml
+unaltraweb:
+  site_profile: unaltreselfie
+  features:
+    news: true
+    blog: true
+    cv: true
+    projects: true
+    publications: true
+    readings: true
+```
+
+Typical content:
+
+- `author` block in `_config.yml`.
+- Localized home pages using `layout: profile`.
+- `_posts/`, `_news/`, `_projects/`, `_bibliography/` and CV assets.
+
+The profile card, social links, highlights and publication summaries come from the core theme.
+Bibliographies use curriculum order: year and month descending, with author and title as stable tie-breakers inside the same date.

data/docs/_documentation/en/12-unaltreprojecte.md

@@ -0,0 +1,38 @@
+---
+title: Build A Project Site With unaltreprojecte
+description: Research project and infrastructure sites.
+lang: en
+ref: profile_unaltreprojecte
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+section: Build A Site
+weight: 240
+permalink: "/profiles/unaltreprojecte/"
+nav_title: Project Site
+---
+Use `unaltreprojecte` for a funded project, lab infrastructure, consortium or research output site.
+
+```yaml
+unaltraweb:
+  site_profile: unaltreprojecte
+  features:
+    publications: true
+    readings: true
+    news: true
+```
+
+Typical content:
+
+- Project landing pages in `_pages/`.
+- Team data in `_data/`.
+- `_outputs/` for reports, datasets, maps and policy briefs.
+- `_projects/` for related or previous projects.
+- Repository and resource pages.
+
+Project cards can use `hero` images and `resources` badges for DOI, GitHub, documentation and datasets.
+Project bibliographies place the newest outputs first by year and month, then use author and title to keep equal-date records deterministic.

data/docs/_documentation/en/13-unaltremanual.md

@@ -0,0 +1,237 @@
+---
+title: Build A Manual With unaltremanual
+description: Manuals, courses and book-like teaching sites.
+lang: en
+ref: profile_unaltremanual
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Build A Site
+weight: 250
+permalink: "/profiles/unaltremanual/"
+nav_title: Manual Site
+---
+Use `unaltremanual` for long-form teaching material, course manuals and book-like documentation.
+
+```yaml
+unaltraweb:
+  site_profile: unaltremanual
+  manual:
+    collection: chapters
+    cover_image: /assets/img/manual-cover.png
+    show_chapter_index: true
+  figure_captions:
+    enabled: true
+    collections: [chapters]
+```
+
+Typical content:
+
+- Localized manual home pages with `layout: manual-home`.
+- Chapters under `_chapters/<lang>/`.
+- Callouts, figures, subfigures, captioned code listings, numbered tables and Mermaid diagrams.
+- Optional manual bibliography.
+- A local `context/writing-profile.md` for audience, voice, terminology, evidence, language, and review rules.
+
+The package scaffold provides a usable default writing profile and a computation configuration that selects the distribution's R and Python workers. It accepts executable chapters under `_chapters` and figure-only sources under `assets/quarto` without copying worker implementation into the site. Revise the writing profile before substantial drafting when the manual has project-specific editorial requirements. The site profile also includes a sticky chapter sidebar, right-hand table of contents, reader font controls and the shared occurrence-level content search.
+
+The scaffold stores manual references in `_bibliography/manual.bib`. Manual bibliographies are alphabetical by contributor name, then year and title. This applies to the general bibliography and to the cited references emitted by a chapter with `manual_references: true`. On the web, the visible reference omits its trailing DOI or URL because the adjacent DOI/LINK buttons and expandable citation panel already expose that access information. The printable PDF keeps DOI and URL text, sorts the general bibliography alphabetically, and inserts an alphabetical references section in each chapter that requests one.
+
+Figures can use independent display constraints for each support. `data-figure-width-web` and `data-figure-height-web` control the browser presentation; `data-figure-width-pdf` and `data-figure-height-pdf` become print constraints while preserving the intrinsic aspect ratio. The older `data-figure-width` remains a shared fallback. Run `manual_source_quality_check` after adding a text-bearing SVG so the MCP can compare its effective text with body text and suggest separate web/PDF widths.
+
+In multilingual manuals, keep the default-language visual unsuffixed and insert `.<lang>` before the complete suffix for translated variants, such as `map.ca.svg`, `plot.ca.qmd`, `bars.ca.vl.json`, or `flow.ca.puml`. The requested language falls back to the unsuffixed source when its variant is absent; an existing localized source with a broken generated output remains a build error.
+
+The manual home lists chapter cards by default. Set `unaltraweb.manual.show_chapter_index: false` globally, or `show_chapter_index: false` in a manual home page's front matter, when the sidebar is sufficient and the home should contain only introductory material.
+
+Unlike `unaltredocs`, `unaltremanual` keeps linear reading affordances such as previous/next chapter navigation. Use it when the primary path through the content is sequential.
+
+## Publishing Current And Stable Editions
+
+The current publishing contract separates an up-to-date reading site from durable editions:
+
+- `latest` is a manual-only deployment built from the reviewed `main` branch.
+- Pushing or merging to `main` does not deploy it. After local checks, required renders, and human review, a maintainer starts deployment manually.
+- When PDF output is enabled, the default `assets/pdf/manual-<lang>.pdf` and `assets/img/manual-cover-<lang>.png` outputs are generated during deployment and are not versioned.
+- The generated home, `manual-release.json`, and PDF editorial metadata identify the selected channel and version.
+- Stable editions use `vYYYY.MM(.N)`: `vYYYY.MM` for the first edition in a month and `vYYYY.MM.N` for an additional edition. They are deferred until a maintainer creates an explicit release, and an ordinary `latest` deployment never creates one.
+- Release checks reject generated `legacy/` or `sandbox/` trees. Keep them outside the current manual content roots.
+
+The generated site README and pull request template require one assigned issue or explicit file reservation, one task branch, one active editor per file, and a small Draft pull request. If edits overlap or conflict, stop and ask the maintainer rather than choosing a side or recreating files.
+
+## Executable Chapters
+
+An executable chapter has an authoritative Quarto, R, Python, or notebook source and a versioned same-stem Markdown result. Ordinary Jekyll and PDF builds consume the committed Markdown and figures; they never execute the analysis automatically.
+
+Supported sources are `.qmd`, `.Rmd`, `.R`, `.py`, and `.ipynb`. Keep sources under a configured source root such as `_chapters/`. A default render publishes:
+
+- `chapter.qmd` as `chapter.md` beside its source.
+- Figures under `assets/img/generated/<lang>/<ref>/`.
+- Provenance and artifact signatures in `.unaltraweb/computations.lock.json`.
+
+Commit the executable source, generated Markdown, generated figures, and lock together. When an executable source exists, edit it rather than the generated `.md`.
+
+### Chapter Metadata
+
+Every executable chapter requires `title`, `lang`, and `ref`. A `.qmd` must also select exactly one engine:
+
+```yaml
+---
+layout: manual-chapter
+title: Computed chapter
+lang: en
+ref: computed-chapter
+weight: 60
+unaltraweb_compute:
+  engine: python
+  inputs:
+    - data/source.csv
+---
+```
+
+`.Rmd` and `.R` infer R; `.py` and `.ipynb` infer Python. Use normal YAML front matter in `.qmd` and `.Rmd`, a `#' ---` roxygen block in `.R`, and a commented `# ---` block in `.py`. A notebook can store the mapping in `metadata.unaltraweb_front_matter` or in the first raw or Markdown cell.
+
+Optional `unaltraweb_compute` fields are `inputs`, `output`, `figures`, and `enabled`. Paths must be project-relative and cannot escape the repository. Generated Markdown must remain under one configured `source_roots` directory; figures must use a strict subdirectory of `generated_assets_root`. Source roots cannot be the project root, cannot overlap each other, and cannot overlap the generated assets root. A custom source root is both a discovery root and a Jekyll source-exclusion root, so keep executable sources and their same-tree Markdown outputs together. `enabled: false` excludes one source. Computation-private metadata is removed from the generated Markdown while public chapter metadata is preserved.
+
+### Project Configuration
+
+The scaffold creates a consumer-owned `.unaltraweb/computations.yml` with both release-selected engines. Extend it to define additional discovery roots and project-specific environment dependencies:
+
+```yaml
+version: 1
+enabled: true
+source_roots:
+  - _chapters
+generated_assets_root: assets/img/generated
+engines:
+  python:
+    image: ghcr.io/dosquartsdedocs/unaltraweb-compute-python@sha256:18cb269811bd4005800382da25a480ec2bca7eac8d0501ad1ef36bad1c0f8cd9
+    lockfiles:
+      - requirements-compute.txt
+    fingerprint_paths:
+      - analysis/helpers
+  r:
+    image: ghcr.io/dosquartsdedocs/unaltraweb-compute-r@sha256:928ffb93f221e09e8b929157dee473b838e061915a2eb67224e4124b85f81837
+    lockfiles:
+      - renv.lock
+```
+
+`unaltraweb_compute.inputs` declares source-specific non-code inputs. Engine `lockfiles` and `fingerprint_paths` describe shared environment dependencies. Files and directories are fingerprinted recursively. Changing a source, declared input, Dockerfile, lockfile, fingerprint path, configuration, or available selected-image identity makes its results stale.
+
+Use `unaltraweb_compute.mode: figure` for executable sources that only generate reusable figures, such as an SVG chart referenced from a hand-written chapter. In that mode, declare every versioned output under `unaltraweb_compute.outputs`; the renderer checks the declared files and records their signatures without creating a generated Markdown chapter.
+
+```yaml
+unaltraweb_compute:
+  engine: python
+  mode: figure
+  outputs:
+    - assets/img/generated/en/palette-reference.svg
+```
+
+The execution container has no network, a read-only root filesystem, dropped capabilities, and resource limits, but the entire project is mounted read-write so Quarto can stage results. Declared inputs provide provenance and freshness checks; they are not a filesystem access policy. Run only trusted chapter code and review the working tree after rendering.
+
+### Render And Check
+
+The MCP exposes the stable workflow without copying implementation targets into the consumer Makefile:
+
+```text
+manual_computation_status
+manual_computation_check
+manual_computation_render
+manual_computation_render_figures
+manual_computation_render(source="_chapters/en/chapter.qmd")
+```
+
+`status` prints JSON and remains informational even when `ok` is false. `check` exits nonzero for missing, stale, modified, or orphaned results. `render` executes explicitly, reuses an available selected worker or pulls it on first use, stages output, serializes publication per project, and replaces managed Markdown and figures with rollback on ordinary errors. `manual_computation_render_figures` renders only stale `mode: figure` sources and never executes chapter-mode sources. Source execution runs without network access and with Quarto caches disabled; image preparation occurs before the network-disabled worker starts.
+
+The shared PDF template keeps normal paragraph spacing instead of stretching sparse pages to the bottom margin, avoids widow and orphan lines, and reserves body text after section headings. Callouts and figures that fit on one page move as a unit to the next page when necessary. Captioned tables reserve their estimated height; genuinely long tables start on a fresh page and may continue only between rows when they exceed one page. Figure and table captions appear above their content and use a smaller sans-serif hierarchy, muted body text, restrained blue numbering, hanging alignment with language-aware hyphenation, and deliberate vertical spacing. Subfigure captions are quieter, a thin rule separates a multi-panel caption from its panels, and the same blue identifies only the numeric prefixes of headings while title text remains neutral.
+
+The first render refuses to overwrite an existing same-stem Markdown file or figure directory that is not recorded in the computation lock. Review the collision before an intentional takeover:
+
+```text
+manual_computation_render(confirm_overwrite=true)
+```
+
+Do not use that confirmation as a permanent default. Do not edit `.unaltraweb/computations.lock.json` manually; review it as generated provenance.
+
+Deleting or disabling a source leaves its lock record and generated artifacts as an orphan, so publication remains blocked. Review and remove the old generated Markdown and figure directory, then run a full `manual_computation_render`; the renderer removes an orphan lock record only after both managed paths are absent.
+
+`make serve`, `make build`, `make test`, profile previews, Playwright checks, PDF operations, and the reusable Pages workflow reject stale results. The internal capture-only preview is the deliberate exception because it must render the artefact that is currently stale. CI checks committed artifacts without recalculating them. Equivalent MCP tools are `manual_computation_status`, `manual_computation_check`, `manual_computation_render`, and `manual_computation_render_figures`.
+
+### Static Vega Figures
+
+Static Vega-Lite and Vega figures use `*.vl.json` and `*.vg.json` sources declared in `.vegavisuals.yml`. A chapter references the specification as a captioned Markdown image; Jekyll and the PDF builder resolve it to the same single manifest output without changing the caption or figure attributes. Prefer SVG when the figure must work identically on the web and in print.
+
+Use the required companion `vegavisuals` MCP and its `initialize_project`, `visualization_status`, `render_visualizations`, and `visualization_check` tools for the source-to-output lifecycle. ContExt registers the companion separately rather than copying it into the site. Run `visualization_check` before PDF status, build, or publication when a manifest exists; the unaltraweb PDF tool does not proxy the separate MCP. Commit the manifest, lock, provider receipt, source data, and generated outputs together.
+
+## PDF Edition
+
+The optional PDF builder runs in a dedicated Docker image containing Pandoc, XeLaTeX, multilingual TeX packages, SVG conversion and Poppler. It reads the same localized manual home and chapter sources as Jekyll, orders chapters by `weight`, resolves rendered Mermaid, PlantUML and manifest-backed Vega outputs, converts Jekyll Scholar citations, alphabetizes Citeproc output from structured contributor metadata, restores printable access links omitted by a CSL, and extracts the first PDF page as the web cover.
+
+```yaml
+unaltraweb:
+  manual:
+    bibliography: true
+    bibliography_file: manual.bib
+    metadata:
+      short_title: COURSE
+      series: Course materials
+      series_subtitle: Learning resources
+      publisher: Example Press
+      edition: First digital edition
+      publication_date:
+        en: August 22, 2026
+      identifier: "urn:isbn:9780000000000"
+      license: CC BY 4.0
+      source: https://example.edu/manual/
+      rights: © The authors
+      subject: Full course name
+      teaching_guides:
+        - degree: First degree name
+          subject_code: "COURSE-01"
+        - degree: Second degree name
+          subject_code: "COURSE-02"
+      institution: University name
+      academic_year: 2026/2027
+      revision_date:
+        en: August 11, 2026
+      instructors:
+        - name: First Teacher
+    pdf:
+      enabled: true
+      languages: [en]
+      output: assets/pdf/manual-{lang}.pdf
+      cover_output: assets/img/manual-cover-{lang}.png
+      cover:
+        image: assets/img/manual-cover-background.jpg
+        institution_logo: assets/img/institution-logo.pdf
+        band_color: "990000"
+```
+
+The cover deliberately contains only structural publication elements: series, title, instructors, main image, institutional logo, and bands. Bibliographic fields, course context, authorship, rights, any declared source or license, and the build's publication channel/selector are rendered on a compact localized editorial-credits page inside the PDF. The same selector appears on the manual home and in generated `manual-release.json`. `publisher`, `edition`, `publication_date`, `identifier`, `license`, and `source` are optional and accept either a scalar or a language map. The builder does not infer them from the institution, revision date, site URL, or other fields; omit values that are not authoritative.
+
+The default template is a two-sided, open-right book: inner and outer margins mirror, folios sit at the outer edge, numbered and unnumbered chapters begin on recto pages, and inserted blank versos carry no headers or folios. Main matter starts at chapter 0, and each chapter opens as a single `number. title` heading. The secondary cover color is shared by complete headings and figure or table labels. PDF syntax highlighting, language headers, and line numbers are guaranteed for Bash, SQL, Python, R, and the semantic `url`, `spreadsheet`, and `filetree` fences. The semantic headers are localized from the document language. Plain, unlabelled, and unsupported fences use an unnumbered verbatim panel without a header. Both panel variants alternate line backgrounds, and long lines wrap inside the printable page.
+
+The PDF workflow checks executable chapters before reading their generated Markdown. Normal site work uses the MCP tools; the additional check/sync targets remain factory-maintainer operations:
+
+```text
+manual_pdf_status
+manual_pdf_build(release_selector="latest")
+manual_pdf_publish                      # dry-run by default
+manual_pdf_publish(dry_run=false, confirm_publish=true)
+build_site(site_profile="unaltremanual", release_selector="latest")
+manual_release_status(selector="latest")
+manual_release_prepare(selector="latest") # dry-run
+manual_release_prepare(selector="latest", dry_run=false, confirm_prepare=true)
+manual_release_check(selector="latest")
+factory: MCP_CONSUMER_WORKSPACE=/path/to/site make manual-pdf-sync
+factory: MCP_CONSUMER_WORKSPACE=/path/to/site make manual-pdf-check
+```
+
+Builds remain under `tmp/manual-pdf/<lang>/`. Each language build creates both the PDF and a PNG extracted from its first page. The release selector is part of the PDF fingerprint, so every PDF build, site build, and candidate operation in one sequence must use the same selector. The default template derives XeTeX's trailer ID from that fingerprint, and the builder canonicalizes the lossless PDF streams with qpdf, so identical inputs and selector produce byte-identical PDFs. A custom template must put `\special{pdf:trailerid [<$trailer-id$><$trailer-id$>]}` on its first output page to preserve that property. Local publication can copy those artefacts to the configured project-relative public paths for review, but it does not commit, push, deploy, or write outside the site. The default public PDF and cover paths are ignored and remain unversioned; the manual deployment rebuilds them from reviewed source. The download button appears when the generated PDF exists among the built site's static files. Chapters can opt out with `pdf: false`.
+
+`manual_release_status` and `manual_release_check` are offline and read-only. `manual_release_prepare` writes only a local evidence bundle below `tmp/manual-release/<selector>/`; it never tags, pushes, deploys, or creates a GitHub release. Stable local candidates are no-clobber while their selector directory exists, but the durable object is the published GitHub tag/release after immutable releases are enabled for the repository, not the disposable `tmp/` directory. A stable sequence must start at the consumer repository root on the exact clean Git commit that will be reviewed on `main`; nested repositories, submodules, Git clean/smudge filters, and versioned PDF outputs are rejected. Start the MCP with the reviewed `ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:<digest>` image rather than a mutable tag. The commit timestamp fixes Jekyll's build time, source and site fingerprints use canonical modes, and the version-2 release manifest records the commit, epoch, and site-build image. Use the same `vYYYY.MM(.N)` selector for PDF build, site build, and candidate preparation, and additionally require approved default-language content, no draft PDF, and a clean editorial quality check. Record the reviewed candidate with `sha256sum tmp/manual-release/<selector>/release-manifest.json`; the stable workflow must reproduce that digest before publication can proceed.

data/docs/_documentation/en/14-unaltredocs.md

@@ -0,0 +1,92 @@
+---
+title: Build A Documentation Portal With unaltredocs
+description: Technical documentation portals.
+lang: en
+ref: profile_unaltredocs
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Build A Site
+weight: 260
+permalink: "/profiles/unaltredocs/"
+nav_title: Documentation Portal
+---
+Use `unaltredocs` for documentation portals with a left index, search, section cards and operational references.
+
+```yaml
+unaltraweb:
+  site_profile: unaltredocs
+  documentation:
+    collection: documentation
+```
+
+Typical content:
+
+- A documentation home document with `layout: documentation-home`.
+- Documents under `_documentation/<lang>/`.
+- `section`, `subsection` and `weight` front matter to build the documentation navigation.
+- Optional documentation profile metadata with `documentation_profiles`.
+- Optional multilingual home pages and documents.
+
+This `unaltraweb` site is itself built with the `unaltredocs` profile.
+
+## Documentation Profiles
+
+`unaltredocs` can expose a small set of reader profiles as a dropdown at the top of the table of contents. Define the profile choices in site config:
+
+```yaml
+unaltraweb:
+  documentation:
+    profiles:
+      - id: local-authors
+        label: Local authors
+      - id: core-developers
+        label: Core developers
+```
+
+Then tag pages that belong mainly to one of those profiles:
+
+```yaml
+---
+title: Installation
+section: User guide
+weight: 20
+documentation_profiles: [local-authors]
+---
+```
+
+The selected profile is stored in `localStorage` and mirrored to the `doc_profile` query parameter, so profile views can be shared. The first dropdown option shows all documentation. Pages without `documentation_profiles` remain visible for every profile.
+
+Direct page links remain available even if the active profile would normally hide that page from navigation. In that case the page shows a short notice instead of hiding the content.
+
+Content search follows the active documentation profile and returns each matching occurrence separately. Matching is whole-word and diacritic-insensitive; opening a result highlights every occurrence on that page and provides previous/next navigation across the filtered result set.
+
+## Reading Model
+
+`unaltredocs` is not a book. Previous/next links are disabled by default because operational documentation is usually task, reference and troubleshooting oriented. If a documentation site needs a linear path, set:
+
+```yaml
+unaltraweb:
+  documentation:
+    previous_next: true
+```
+
+For full manuals, courses or books, prefer `unaltremanual`.
+
+## Version Metadata
+
+Version labels can be recorded in front matter before a site needs full versioned builds:
+
+```yaml
+introduced_in: "0.4"
+changed_in: "0.6"
+deprecated_in:
+removed_in:
+```
+
+Use these keys to annotate when a page or feature changed. Separate `/latest/`, `/stable/` or `/v1.0/` documentation trees should only be added when a project needs complete historical documentation.