unaltraweb 0.3.0

data/docs/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+group :jekyll_plugins do
+  gem "unaltraweb", path: ".."
+end

data/docs/_config.yml

@@ -0,0 +1,83 @@
+title: unaltraweb
+description: Reusable Jekyll core for academic, research project and documentation websites.
+url: https://dosquartsdedocs.github.io
+baseurl: /unaltraweb
+lang: en
+default_lang: en
+languages: [en, es, ca]
+icon: "brand/dosquartsdedocs-logo.svg"
+theme: unaltraweb
+
+plugins:
+  - unaltraweb
+  - jekyll-3rd-party-libraries
+  - jekyll-archives-v2
+  - jekyll-cache-bust
+  - jekyll-email-protect
+  - jekyll-feed
+  - jekyll-get-json
+  - jekyll-imagemagick
+  - jekyll-link-attributes
+  - jekyll-minifier
+  - jekyll-paginate-v2
+  - jekyll-regex-replace
+  - jekyll/scholar
+  - jekyll-sitemap
+  - jekyll-socials
+  - jekyll-tabs
+  - jekyll-toc
+  - jekyll-twitter-plugin
+  - jemoji
+
+include: ["_pages"]
+third_party_libraries: {}
+search_enabled: true
+footer_fixed: true
+
+collections:
+  documentation:
+    output: true
+    sort_by: weight
+
+unaltraweb:
+  site_profile: unaltredocs
+  features:
+    docs: true
+    blog: false
+    cv: false
+    projects: false
+    publications: false
+    metrics: false
+    manual: false
+  documentation:
+    collection: documentation
+    logo: /assets/img/brand/dosquartsdedocs-logo.svg
+    logo_inverse: /assets/img/brand/dosquartsdedocs-logo-white.svg
+    logo_cafe: /assets/img/brand/dosquartsdedocs-logo.svg
+    profiles:
+      - id: github-publishers
+        label: GitHub publishers
+      - id: local-authors
+        label: Local authors
+      - id: site-designers
+        label: Site designers
+      - id: contributors
+        label: Contributors
+      - id: core-developers
+        label: Core developers
+  figure_captions:
+    enabled: true
+    collections: [documentation]
+
+defaults:
+  - scope:
+      path: ""
+      type: documentation
+    values:
+      lang: en
+      layout: documentation-page
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md

data/docs/_documentation/en/01-quick-start.md

@@ -0,0 +1,115 @@
+---
+title: Choose Your unaltraweb Workflow
+description: Create and edit an unaltraweb site through GitHub or locally with Docker.
+lang: en
+ref: quick_start
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Start Here
+weight: 10
+permalink: "/quick-start/"
+nav_title: Start Here
+---
+<p class="lede">Create a clean profile-specific site with the package-owned <code>new_web</code> operation. Its generated README starts with the GitHub Web workflow for content editors; maintainers use local Docker for previews, checks, and renders.</p>
+
+## Choose A Path
+
+- **Local Docker**: requires Git, Docker and Make. Good for previewing the site, larger edits, validation, and rendered-output review.
+- **GitHub-only**: no local setup. Good for editing pages, posts, bibliography records, project data and small configuration changes; deployment is manual.
+
+## GitHub-only Editing
+
+1. Push a site created by `new_web` to a new repository.
+2. Read its generated `README.md` to confirm the selected profile, editable paths, image rules, and paths that must not be changed in GitHub Web.
+3. Open an issue and get assigned, or make an explicit file reservation and wait for maintainer acceptance. Only one active editor works on a file.
+4. Create one branch for the task and never edit `main` directly.
+5. Make a small content change in the profile-appropriate paths and open a Draft pull request linked to the issue.
+6. If a conflict appears, stop and ask the maintainer rather than overwriting work.
+7. The maintainer checks the branch locally, runs required renders, reviews the result, and merges it.
+8. The maintainer runs the manual deploy workflow only when the reviewed `main` branch should be published.
+
+This path is enough for small content updates such as adding a bibliography entry, editing a page, updating project data or correcting text. The detailed protocol is in [Edit Safely In GitHub Web](../github-web-editing/).
+
+## Local Docker Editing
+
+For an agent-first IDE session, create or select an empty Git repository, open that directory as the workspace, register the `unaltraweb` factory, and restart the IDE so `${workspaceFolder}` is used as the confined consumer root. Then call `new_web`; the generated `AGENTS.md` is the durable local contract for subsequent agents.
+
+Create the site through the MCP, the installed package CLI, or this factory checkout:
+
+```bash
+unaltraweb-mcp --project ./my-site new-web --site-profile unaltreselfie --title "My site" --default-lang en
+# or: MCP_CONSUMER_WORKSPACE=./my-site make mcp-new-web NEW_WEB_PROFILE=unaltreselfie SITE_TITLE="My site" DEFAULT_LANG=en
+```
+
+The scaffold is bundled with the Python package and MCP image. Creation aborts before writing when a managed path is a symlink or a differing file already exists. A manual also receives a default-language chapter directory, computation source/output roots, `README.md`, `AGENTS.md`, and a package baseline for conservative runtime updates. After pushing the generated site, install Git, Docker and GNU Make, then clone it normally:
+
+```bash
+git clone https://github.com/YOUR-ORG/YOUR-SITE.git
+cd YOUR-SITE
+make serve
+```
+
+The reusable layouts, styles, plugins and scripts come from the `unaltraweb` gem declared in the site's `Gemfile`. The selected MCP image provides the normal containerized build runtime. When working against an unpublished core candidate, build that image explicitly in the factory checkout first; a generated site reports this remediation instead of silently falling back to another version.
+
+Use these commands during normal local work:
+
+```bash
+make serve
+make build
+make test
+make down
+```
+
+The generated GitHub Actions workflow publishes to Pages only when a maintainer starts it manually. A push, local build, or local render does not deploy the site.
+
+When developing `unaltraweb` and the template together, use this local port convention:
+
+- `unaltraweb`: `4000`.
+- `unaltreselfie`: `4001`.
+- `unaltreprojecte`: `4002`.
+- `unaltremanual`: `4003`.
+- `unaltredocs`: `4004`.
+
+Each generated repository has one profile-specific scaffold. Create a separate temporary site when comparing another profile instead of mixing profile content into the published repository.
+
+## Windows
+
+The supported Windows path is WSL2 with Docker Desktop and Docker's WSL integration enabled. Run the same `make` commands inside the WSL Linux shell.
+
+Native PowerShell without WSL2 is not the primary supported path yet.
+
+## Profiles
+
+Select one profile in `_config.yml`:
+
+```yaml
+unaltraweb:
+  site_profile: unaltreselfie
+```
+
+Available profiles are:
+
+- `unaltreselfie`: personal academic or professional site.
+- `unaltreprojecte`: research project site.
+- `unaltremanual`: manual, course or book-like site.
+- `unaltredocs`: documentation site.
+
+`new_web` provides a separate clean scaffold for every profile. The optional `unaltraweb-template` fixture contains richer examples for all four profiles. This documentation site is called `unaltraweb`; it is the reference for the platform and uses real examples of supported behavior.
+
+## Core Development
+
+When changing `unaltraweb` and the template side by side, point the template at the local core checkout:
+
+```bash
+make serve LOCAL_CORE=../unaltraweb
+make build LOCAL_CORE=../unaltraweb
+make serve-allprofiles LOCAL_CORE=../unaltraweb
+```
+
+This is for core/theme development, not for normal content editing.

data/docs/_documentation/en/02-tools.md

@@ -0,0 +1,146 @@
+---
+title: Tools For Local Work
+description: What users and maintainers need to work with unaltraweb.
+lang: en
+ref: tools_requirements
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- contributors
+- core-developers
+section: Work Locally
+weight: 110
+permalink: "/tools/"
+nav_title: Local Tools
+---
+<p class="lede">Most site authors can choose between the preferred local Docker workflow and a GitHub-only workflow for contributors who cannot work locally. The local path is intentionally small: Git, Docker and Make.</p>
+
+## User Paths
+
+| Path | Required tools | Best for |
+|---|---|---|
+| Local Docker | Git, Docker, GNU Make | Previewing, larger edits, screenshots, tests, and rendered-output review |
+| GitHub-only | Browser, GitHub account, repository created from the template | Small content edits, bibliography entries, page text, YAML data and configuration changes, followed by a manual deploy workflow |
+| Windows local | WSL2, Docker Desktop with WSL integration, Git and Make inside WSL | The supported Windows equivalent of the local Docker path |
+| Core maintenance | Docker, Git, GitHub Actions, GHCR access; Ruby/Bundler optional for direct debugging | Changing layouts, plugins, Sass, scripts, workflows and the shared runtime image |
+
+## Local Runtime
+
+The template uses the shared runtime image by default:
+
+```bash
+ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
+```
+
+That image provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling needed by local commands. The GHCR package must be public before unauthenticated users can pull it.
+
+## Generated Site Commands
+
+Clean sites created by `new_web` expose the Dockerized core workflow:
+
+```bash
+make serve
+make build
+make test
+make down
+```
+
+Inspect the selected component contract and local project pins without network access:
+
+```bash
+unaltraweb-mcp doctor --project .
+unaltraweb-mcp doctor --project . --docker  # local image inspection only; never pulls
+unaltraweb-mcp --project . mcp site-doctor
+unaltraweb-mcp --project . mcp scaffold-sync
+unaltraweb-mcp --project . mcp html-audit
+```
+
+The generated `make test` builds and runs the offline HTML audit. `build_site` returns the same audit after a successful build. External URLs are inventoried but never fetched.
+
+## Calibre Metadata Import
+
+The installed host CLI can import book metadata and `cover.jpg` files from an external Calibre library into `_books/` and `assets/img/books/`. It never copies ebook files. The command is a dry run unless `--write` is explicit:
+
+```bash
+unaltraweb-mcp --project /path/to/site import-calibre \
+  --library /path/to/Calibre-Library \
+  --source-key geography \
+  --collection-name "Geography readings" \
+  --profiles unaltreselfie
+
+# Repeat the reviewed command with --write to create project files.
+```
+
+Use `--ids 12,34` or `--limit 10` to select records. `--refresh-existing` updates a Markdown file only when its front matter has the same `calibre_source` and `calibre_id`; unrelated Markdown and cover collisions stop the whole preflight without writing. Library paths and cover sources are checked for traversal and symlinks. This is deliberately a host CLI command, not an MCP tool, because external Calibre libraries are not mounted in the MCP container.
+
+## Integration Template Commands
+
+Run these from a child site created from `unaltraweb-template`:
+
+```bash
+make serve
+make build
+make publish
+make test
+make screenshots
+make web-capture-status
+make web-capture-render WEB_CAPTURE_SOURCE=assets/captures/chapter.capture.yml
+make web-capture-check
+make visualization-status
+make visualization-render
+make visualization-check
+make metrics-update
+make cv-preview CV_PDF=assets/pdf/cv.pdf CV_PREVIEW=assets/img/cv-preview.jpg
+make down
+```
+
+## Core Documentation Commands
+
+Run these from the `unaltraweb` repository when working on this reference site:
+
+```bash
+make docs-serve DOCKER_IMAGE=unaltraweb:dev
+make docs-build DOCKER_IMAGE=unaltraweb:dev
+make docs-publish DOCKER_IMAGE=unaltraweb:dev
+make docs-down
+```
+
+After the GHCR image is public, `DOCKER_IMAGE` can be omitted.
+
+Useful profile commands:
+
+```bash
+make serve SITE_PROFILE=unaltremanual
+make serve-unaltreselfie
+make serve-unaltreprojecte
+make serve-unaltremanual
+make serve-unaltredocs
+make serve-allprofiles
+```
+
+## Ports
+
+When the core docs and all template profiles are running together, use this convention:
+
+- `4000`: `unaltraweb` documentation.
+- `4001`: `unaltreselfie`.
+- `4002`: `unaltreprojecte`.
+- `4003`: `unaltremanual`.
+- `4004`: `unaltredocs`.
+
+## Optional Tools
+
+- Node/npm are only needed for formatting and frontend development tasks in the core repository.
+- Playwright is pulled through its Docker image by the template tests; users do not need to install browsers manually.
+- Python dependencies are installed inside the local workflow for metrics and bibliography tooling.
+- Diagram rendering is delegated to the shared `diavisuals` MCP/CLI renderer. Jekyll rewrites diagram text sources to SVG and keeps `*.edited.svg` files as author-owned overrides.
+- Static Vega-Lite and Vega rendering is delegated to the shared `vegavisuals` MCP/CLI factory. Set `VEGAVISUALS_PATH` to a sibling checkout or `VEGAVISUALS_CLI` to an installed executable when a project contains `.vegavisuals.yml`; projects without a manifest skip these commands.
+
+## Publishing Checklist
+
+- Generated-site route: enable GitHub Pages with GitHub Actions as the source and run the manual deploy workflow when needed.
+- Keep deploy workflows as thin `workflow_dispatch` wrappers pinned to a reviewed full commit SHA of `dosquartsdedocs/unaltraweb/.github/workflows/site-deploy.yml`.
+- The optional integration template may retain its local `gh-pages` publishing target for testing that separate workflow.
+- After the first Docker publish, make `ghcr.io/dosquartsdedocs/unaltraweb` public.
+- Confirm `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.3.0` works without `docker login`.

data/docs/_documentation/en/03-usage.md

@@ -0,0 +1,107 @@
+---
+title: Run And Preview A Site
+description: How to create, edit, preview and publish unaltraweb sites.
+lang: en
+ref: usage_workflow
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Work Locally
+weight: 120
+permalink: "/usage/"
+nav_title: Run And Preview
+---
+<p class="lede">An <code>unaltraweb</code> site should keep content and local choices in the child repository. Shared rendering, styles, plugins, scripts and workflows stay in the core.</p>
+
+## Create A Site
+
+1. Call `new_web` with one `unaltraweb.site_profile` and the site identity/language settings.
+2. Inspect the generated `_config.yml` and localized home page.
+3. Reserve a focused task, create one branch, and open a small Draft pull request. Never edit `main` directly, and allow only one active editor per file.
+4. Edit content and data files. MCP agents should read a source hash, review the default `site_source_write` dry-run, then apply the exact CAS update.
+5. Stop and ask the maintainer if another task overlaps or a conflict appears.
+6. The maintainer runs `site_doctor`, `profile_check`, `site_check`, `build_site`, and required renderers, then reviews the returned HTML audit and rendered outputs.
+7. After review, the maintainer merges the pull request and manually runs the generated GitHub Pages workflow when publication is intended.
+
+CLI equivalent:
+
+```bash
+unaltraweb-mcp --project ./example-site new-web --site-profile unaltreselfie --title "Example Site" --url https://example.github.io --baseurl /example-site
+```
+
+Minimal profile selection:
+
+```yaml
+title: Example Site
+url: https://example.github.io
+baseurl: /example-site
+
+unaltraweb:
+  site_profile: unaltreselfie
+```
+
+## What To Edit
+
+| Path | Purpose |
+|---|---|
+| `_config.yml` | Site identity, URL, languages, profile, feature flags and profile-specific options |
+| `_pages/` | Home, navigation pages, profile pages, manuals and documentation landing pages |
+| `_posts/` and `_news/` | Blog posts and short dated announcements |
+| `_projects/`, `_outputs/`, `_books/`, `_theses/` | Structured collections rendered by reusable layouts |
+| `_chapters/` and `_documentation/` | Manual chapters and documentation pages |
+| `_bibliography/` | Publication and manual bibliography BibTeX files |
+| `_data/` | Team, metrics, repositories, translations and other structured data |
+| `_sass/_site-custom.scss` | Local colors, type, spacing and small component overrides |
+| `assets/` | Images, PDFs, diagrams, downloads and generated previews |
+
+## What Not To Copy
+
+Do not copy core `_layouts`, `_includes`, `_sass` or plugin files into a child site unless you are intentionally making a local override. Copying core code blocks future updates from the gem.
+
+Use local overrides only when the site genuinely needs different behavior:
+
+```text
+_layouts/my-local-page.liquid
+_sass/_site-custom.scss
+assets/img/local-brand.svg
+```
+
+## Preview And Build Locally
+
+```bash
+make serve
+make build
+make test
+make down
+```
+
+The generated repository contains one profile. Create a separate temporary site with `new_web` to compare another profile. Publication runs through the generated manual GitHub Pages workflow and is never triggered by a push or these local commands.
+
+## Update Model
+
+- Gem updates change layouts, includes, Sass, plugins and scripts.
+- Docker image updates change local runtime dependencies and are published manually.
+- Reusable workflow updates change optional GitHub build and deploy behavior.
+- Package scaffold changes affect newly generated sites. Existing generated repositories can review `scaffold_sync`, which manages exactly `.gitignore`, `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`, `.github/dependabot.yml`, `Makefile`, `Gemfile`, `Gemfile.lock`, `.github/pull_request_template.md`, and `.github/workflows/deploy.yml` from `.unaltraweb/scaffold.json`. It can adopt bytes that already equal the current package payload without rewriting the file. A conflict aborts the entire apply, and retired entries are removed from the baseline without deleting project files. Synchronization never changes site-owned README/agent guidance, config, or content.
+
+## Safe MCP Editing
+
+`site_source_read`, `site_source_write`, and `site_source_delete` are deliberately restricted to `_config.yml`, Markdown/HTML content collections, YAML/JSON/CSV below `_data/`, and Markdown below `context/`. They do not expose generic filesystem access and cannot mutate workflows, runtime files, core overrides, bibliography, assets, or generated output. Writes default to dry-run and use SHA-256 optimistic concurrency; destructive deletes additionally require explicit confirmation and can never remove `_config.yml`.
+
+Dependabot can stay enabled for Bundler and GitHub Actions in child sites, but deploy workflows should remain manual so dependency pull requests do not consume deploy minutes automatically.
+
+## Content-Only Work
+
+The GitHub web UI is enough for common edits when editors follow the [issue, reservation, branch, and Draft pull request protocol](../github-web-editing/):
+
+- add or correct a BibTeX record;
+- edit a Markdown page;
+- add a post or news item;
+- update a team member in `_data/`;
+- change profile feature flags in `_config.yml`.
+
+The maintainer uses local Docker to inspect the rendered result before merge. Publication remains an explicit manual workflow action after the reviewed change reaches `main`.

data/docs/_documentation/en/04-jekyll-basics.md

@@ -0,0 +1,51 @@
+---
+title: Jekyll Basics For Child Sites
+description: The minimum Jekyll concepts needed to edit an unaltraweb site safely.
+lang: en
+ref: jekyll_basics
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Work Locally
+weight: 130
+permalink: "/jekyll-basics/"
+nav_title: Jekyll Basics
+---
+`unaltraweb` sites are normal Jekyll sites with a reusable theme gem. You do not need to edit the theme to edit content.
+
+## Front Matter
+
+Every page starts with YAML front matter:
+
+```yaml
+---
+title: Projects
+layout: page
+lang: en
+permalink: /en/projects/
+profiles: [unaltreselfie]
+feature: projects
+---
+```
+
+## Collections
+
+Collections are folders whose entries are rendered by layouts:
+
+- `_projects/` for project cards and project pages.
+- `_outputs/` for research outputs.
+- `_books/` for readings.
+- `_chapters/` for manuals.
+- `_documentation/` for documentation pages.
+
+## Theme Resolution
+
+Jekyll looks in the child repository first and then in the `unaltraweb` gem. This lets a site override a layout intentionally, but normal sites should avoid copying core files.
+
+## Static Build Rule
+
+Normal builds should not fetch external APIs. Metrics, diagrams and PDF previews are generated by explicit commands before the site build.

data/docs/_documentation/en/05-pages-collections.md

@@ -0,0 +1,68 @@
+---
+title: Create Pages, Collections, And Navigation
+description: How editable content becomes navigation and rendered pages.
+lang: en
+ref: pages_collections_navigation
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Build A Site
+weight: 210
+permalink: "/pages-collections-navigation/"
+nav_title: Pages And Navigation
+---
+Child sites keep navigation pages in `_pages/` and structured entries in collections.
+
+## Navigation Pages
+
+Set `nav: true` to add a page to the top navigation for profiles that use standard nav.
+
+```yaml
+---
+title: Publications
+layout: bib
+lang: en
+ref: publications
+profiles: [unaltreselfie]
+feature: publications
+nav: true
+nav_order: 40
+permalink: /en/publications/
+---
+```
+
+## Profile Filtering
+
+Use `profiles` to keep a multi-profile starter repository without publishing every page in every profile.
+
+```yaml
+profiles: [unaltreprojecte]
+```
+
+## Feature Flags
+
+Feature flags hide standard sections from navigation without deleting content.
+
+```yaml
+unaltraweb:
+  features:
+    publications: true
+    blog: false
+```
+
+## Documentation Pages
+
+Documentation pages use the `documentation` collection and a `section` value for the left index.
+
+```yaml
+---
+title: Install and run locally
+section: User guides
+weight: 30
+---
+```