unaltraweb 0.3.0

data/docs/_documentation/en/15-profile-checklist.md

@@ -0,0 +1,39 @@
+---
+title: Check Profile Features Before Publishing
+description: What to check before choosing and publishing a profile.
+lang: en
+ref: profile_checklist
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Build A Site
+weight: 270
+permalink: "/profiles/checklist/"
+nav_title: Feature Checklist
+---
+Before publishing a child site, check the profile contract rather than only the visual layout.
+
+## Configuration
+
+- `unaltraweb.site_profile` is set to one profile.
+- `unaltraweb.features` matches the sections you intend to publish.
+- `url` and `baseurl` match the GitHub Pages target.
+- `languages` includes only the languages you are actually maintaining.
+
+## Content
+
+- Every page has `lang`, `ref` and a stable `permalink`.
+- Profile-specific pages use `profiles`.
+- Collection entries use the fields expected by their layouts.
+
+## Local Review
+
+```bash
+make build SITE_PROFILE=unaltredocs
+make test SITE_PROFILE=unaltredocs
+```

data/docs/_documentation/en/20-syntax.md

@@ -0,0 +1,353 @@
+---
+title: Write Content With Markdown Extensions
+description: unaltraweb syntax beyond standard Markdown.
+lang: en
+ref: content_syntax
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+section: Design And Customize
+weight: 310
+permalink: "/syntax/"
+nav_title: Markdown Extensions
+---
+<p class="lede"><code>unaltraweb</code> keeps ordinary Markdown readable, then adds a small set of conventions for profiles, callouts, figures, diagrams, cards and static academic data.</p>
+
+## Profile And Feature Front Matter
+
+Use profile filters when a page should only exist in some site families:
+
+```yaml
+---
+title: Projects
+layout: page
+profiles: [unaltreselfie]
+feature: projects
+nav: true
+permalink: /en/projects/
+---
+```
+
+The page is written only for matching profiles. The `feature` key controls navigation visibility through `_config.yml`:
+
+```yaml
+unaltraweb:
+  features:
+    projects: true
+    publications: true
+    blog: false
+```
+
+## Callouts
+
+Nested blockquotes become teaching callouts in manual-style content. A single `>` remains a normal quotation.
+
+```markdown
+>> A note or tip.
+
+>>> A worked example.
+
+>>>> A warning.
+
+>>>>> Learning objectives.
+
+>>>>>> A caution or danger note.
+```
+
+Rendered by the same parser:
+
+>> **Note.** Use this for a short conceptual pause.
+
+>>> **Example.** Show the command, formula or reasoning step that makes the concept concrete.
+
+>>>> **Warning.** Flag steps that can damage data, confuse students or break a build.
+
+Use `>>>>>` learning objectives sparingly, normally once after a short chapter or major-section introduction. Do not put them before any orienting prose, and do not use them as repeated mid-section reminders; use prose, tables or ordinary notes for intermediate criteria.
+
+## Manual Heading Levels
+
+Manual chapters number three body levels:
+
+```markdown
+## Section
+### Subsection
+#### Fourth-level subsection
+```
+
+The secondary page TOC includes `##` and `###`. A `####` heading remains numbered in the text but is intentionally omitted from that TOC. Use it for a cohesive minor subdivision, not as a formatting substitute for every short item. Do not write standalone fake headings such as `**Source.**`; use a real `####` heading or keep the bold run-in and its explanation in one paragraph.
+
+## Definition Lists
+
+Definition lists render compact terminology as dictionary-style entries on the web and in the manual PDF:
+
+```markdown
+Spatial reference system
+: Rules and parameters used to interpret coordinates in a defined spatial framework.
+
+Map projection
+: Mathematical transformation used to represent a curved surface on a plane.
+```
+
+Use them for concise vocabulary. Develop concepts that need arguments, examples, discussion, or limitations in normal paragraphs.
+
+## Figures And Captions
+
+For pages with figure captions enabled, use the Markdown image title as the caption:
+
+```markdown
+![Digitizing workflow]({{ site.baseurl }}/assets/img/workflow.svg "Main editing steps")
+```
+
+To narrow the space assigned to one figure without changing its height, set a
+CSS width with `data-figure-width`. The figure remains centred and cannot exceed
+the available width. The PDF builder maps `rem` values against its 60-rem
+reading column and caps the result at the printable width:
+
+```markdown
+![Project folders](assets/diagrams/folders.puml "Recommended project structure"){: data-figure-width="22rem"}
+```
+
+Multi-panel figures use a fenced subfigure block:
+
+```markdown
+::: subfigures a+b/c "Three views of the same exercise"
+![Interface]({{ site.baseurl }}/assets/img/interface.svg "Interface")
+![Map]({{ site.baseurl }}/assets/img/map.svg "Map")
+![Diagram]({{ site.baseurl }}/assets/img/diagram.svg "Diagram")
+:::
+```
+
+The layout string uses `/` for rows and `+` for columns. The example above renders panels `a`, `b` and `c` as one numbered figure on the web and in the PDF.
+Use this component when juxtaposition is the teaching task: before/after states, controlled alternatives, a short sequence, or complementary views that need one shared caption. Prefer compact layouts such as `a+b` and `a+b/c`, and use them selectively. Images that merely share a topic should normally remain separate figures.
+
+## Numbered Tables
+
+Manual chapters can number teaching tables with localized labels:
+
+```markdown
+::: table "Weekly work rhythm"
+| Week | Focus | Output |
+| --- | --- | --- |
+| 1 | Orientation | Reading notes |
+| 2 | Data setup | Working project folder |
+:::
+```
+
+Cells may contain inline code spans such as `` `=SUM(A2:A10)` ``. The manual renderer preserves these as inline `<code>` elements on the web; if a consumer project still shows literal backticks inside numbered tables, update its `unaltraweb` lock file or use explicit HTML `<code>` as a temporary compatibility fallback.
+
+## Diagram Sources
+
+Reference diagram source files as images. The Jekyll plugin rewrites Mermaid and
+PlantUML text sources to SVG files, rendering them through `diavisuals` when the
+shared renderer is available:
+
+```markdown
+![Vector workflow]({{ site.baseurl }}/assets/diagrams/vector-workflow.mmd "Vector workflow")
+```
+
+SVG is the preferred output because it remains editable. The lookup order
+prefers edited diagrams first:
+
+```text
+vector-workflow.mmd.edited.svg
+vector-workflow.mmd.svg
+```
+
+When `*.edited.svg` exists, the build keeps using it and does not overwrite it.
+Agents changing the diagram source should ask whether to keep the edited SVG or
+replace it with a regenerated version.
+
+## Static Vega Sources
+
+Reference a manifest-backed Vega-Lite (`*.vl.json`) or Vega (`*.vg.json`) specification as a captioned image:
+
+```markdown
+![Quarterly totals](assets/charts/quarterly.vl.json "Quarterly totals"){: data-figure-width="42rem"}
+```
+
+`.vegavisuals.yml` must declare that source exactly once and name its generated output. A source referenced as a web image must produce SVG or PNG; PDF output is valid only for PDF-specific use and cannot be placed in an HTML `img`. Jekyll and the manual PDF builder replace only the image URL, preserving the title caption and Kramdown attributes. SVG is recommended for web/PDF parity. Run `make visualization-render` after source or data changes and `make visualization-check` before publication; rendering and freshness remain owned by the companion `vegavisuals` factory.
+
+## Selector-Based Web Captures
+
+Store a web capture recipe under `assets/` and reference the recipe as the image source:
+
+```markdown
+![Chapter navigation](assets/captures/chapter.capture.yml "Annotated chapter navigation")
+```
+
+The recipe uses a local preview path and CSS selectors rather than arbitrary browser scripts:
+
+```yaml
+version: 1
+path: /manual/en/chapter/
+viewport: {width: 1440, height: 900}
+theme:
+  setting: cafe
+waits:
+  selectors: [.manual-layout]
+inputs:
+  - _chapters/en/chapter.md
+annotations:
+  - id: chapter-navigation
+    selector: .manual-sidebar
+    kind: arrow
+    text: Chapter navigation
+```
+
+`web_capture_render` starts an ephemeral site and browser on an internal Docker network, keeps the untouched `*.capture.png`, and generates a self-contained `*.capture.svg` with editable vector layers. A manually reviewed `*.capture.edited.svg` wins over the generated SVG and is never overwritten. Commit the recipe, PNG, SVG, and `.unaltraweb/web-captures.lock.json` together. `web_capture_check` blocks stale output and stale edited overrides. Ordinary Jekyll and PDF builds consume only the selected SVG and do not run Chromium.
+
+## Code Fences
+
+Use language names for syntax highlighting. Rouge renders recognized languages on the web and the manual PDF renderer guarantees `listings` highlighting for `bash`, `shell`, `sh`, `sql`, `python`, and `r`. Use `url` for URLs or decomposed requests, `spreadsheet` for spreadsheet formulas, and `filetree` for file and directory listings; these semantic fences receive localized headers and dedicated highlighting on both outputs. Recognized blocks receive a compact language header and line numbers; web line numbers are hidden from assistive technology and excluded when copying code. A fence declared as `text`, `plaintext`, `plain`, or `txt`, a fence with no language, or a language unsupported by the renderer becomes an unnumbered verbatim panel without a header. Alternating line backgrounds aid tracking, and PDF lines wrap inside the printable page. Inline code uses single backticks and is styled separately from prose:
+
+````markdown
+```bash
+ogrinfo data/raw/roads.gpkg -so roads
+```
+
+```sql
+SELECT ST_Area(geom::geography) AS area_m2
+FROM protected_areas;
+```
+
+```python
+import geopandas as gpd
+```
+
+```r
+library(sf)
+```
+
+```
+Generic output or a value copied from an application.
+```
+````
+
+Wrap one fence in a `listing` block when it needs a descriptive caption and an index entry:
+
+````markdown
+::: listing "Inspect the roads layer"
+```bash
+ogrinfo data/raw/roads.gpkg -so roads
+```
+:::
+````
+
+The opening line requires a non-empty double-quoted caption and the wrapper must contain exactly one fenced block. Captioned code examples have localized, chapter-scoped numbers on the web and in the PDF. The printable manual emits lists of figures, tables, and code examples after the table of contents when those elements are present. Ordinary fences remain valid and do not enter the list of code examples.
+
+## Links, Citations, And Equations
+
+The web and manual PDF distinguish bibliographic citations, external URLs, and internal links by color. Use Jekyll Scholar for citations, ordinary Markdown for external links, and stable heading identifiers for internal links:
+
+```markdown
+{% raw %}{% cite sourceKey %}{% endraw %}
+[OGC standards](https://www.ogc.org/)
+
+## Normalization {#normalization}
+See [the normalization criteria](#normalization).
+```
+
+Inline mathematics uses `$...$`; displayed equations use `$$...$$` on separate lines and are numbered by default. Add a stable `eq:` label when the text refers to an equation; use `equation*` explicitly for an unnumbered display:
+
+```markdown
+\begin{equation}
+\bar{x}_w = \frac{\sum_i w_i x_i}{\sum_i w_i}
+\label{eq:weighted-mean}
+\end{equation}
+
+Equation $\eqref{eq:weighted-mean}$ defines the weighted mean.
+```
+
+## Hero Images
+
+Pages can use a compact hero image:
+
+```yaml
+---
+layout: page
+title: Example Page
+hero:
+  image: /assets/img/example-hero.jpg
+  alt: Short accessible description
+  caption: Optional caption
+  source: Optional source name
+  source_url: https://example.org/source
+  position: center
+---
+```
+
+Project entries can also define `hero` for cards and project pages.
+
+## Project Resources
+
+Project pages can expose datasets, repositories, papers and documentation as icon badges:
+
+```yaml
+---
+layout: project
+title: Example Project
+resources:
+  - type: zenodo
+    label: Zenodo dataset
+    url: https://zenodo.org/records/1000001
+    doi: 10.5281/zenodo.1000001
+  - type: github
+    label: Source code
+    url: https://github.com/example/project
+  - type: documentation
+    label: Technical notes
+    url: https://example.org/docs/example
+---
+```
+
+Built-in resource types include `zenodo`, `doi`, `dataset`, `data`, `code`, `github`, `repository`, `documentation`, `docs`, `map`, `publication`, `paper`, `report`, `website` and `link`.
+
+## CV Preview Cards
+
+Use the CV preview include when a PDF is the source of truth:
+
+```yaml
+---
+cv_pdf: /assets/pdf/cv.pdf
+cv_preview: /assets/img/cv-preview.jpg
+---
+```
+
+{% raw %}
+```liquid
+{% include cv-download-card.liquid pdf=page.cv_pdf preview=page.cv_preview title="CV" %}
+```
+{% endraw %}
+
+Generate the preview locally:
+
+```bash
+make cv-preview CV_PDF=assets/pdf/cv.pdf CV_PREVIEW=assets/img/cv-preview.jpg
+```
+
+## Documentation Sections
+
+The `unaltredocs` profile uses `_documentation` documents with front matter that drives the left index:
+
+```yaml
+---
+title: Installation
+section: Getting Started
+subsection: Local workflow
+weight: 20
+documentation_profiles: [local-authors]
+---
+```
+
+## Static Metrics
+
+Publication metrics are updated before builds and written to local files. Jekyll builds do not call OpenAlex, Crossref, Scimago or Google Scholar.
+
+```text
+bibliometrics_update
+bibliometrics_check
+```

data/docs/_documentation/en/21-themes.md

@@ -0,0 +1,103 @@
+---
+title: Theme And Visual Design
+description: Theme modes, local style overrides and JavaScript integration in unaltraweb.
+lang: en
+ref: theme_modes
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- site-designers
+- contributors
+section: Design And Customize
+weight: 320
+permalink: "/themes/"
+nav_title: Themes
+---
+<p class="lede"><code>unaltraweb</code> supports system, light, coffee and dark theme settings. The modes are part of the user interface and are covered by the template render smoke tests.</p>
+
+## Modes
+
+- **Light**: high-contrast default reading mode for normal pages and profile sites.
+- **Coffee**: warm brown reading mode for manuals, long-form documentation and course material.
+- **Dark**: dark mode with matching integration state for embedded libraries and generated diagrams.
+
+The switch rotates through:
+
+```text
+system -> light -> coffee -> dark -> system
+```
+
+`system` follows the browser preference and resolves to light or dark.
+
+## Data Attributes
+
+The active theme state is exposed on `<html>`:
+
+```html
+<html data-theme-setting="cafe" data-theme="cafe" data-theme-integration="light" data-site-profile="unaltremanual">
+```
+
+Use these attributes for local CSS and automated checks. Do not infer the active profile from URLs.
+
+## Local Sass Overrides
+
+Create `_sass/_site-custom.scss` in the child site. It is imported after the core styles.
+
+```scss
+:root {
+  --global-theme-color: #2f6f5e;
+  --global-hover-color: #2f6f5e;
+}
+
+html[data-theme="cafe"] {
+  --global-theme-color: #6f4e1f;
+}
+
+html[data-site-profile="unaltremanual"] .manual-sidebar {
+  border-color: var(--global-theme-color);
+}
+```
+
+## Custom Coffee Palette
+
+Use CSS custom properties to customize a built-in mode without changing the theme switcher:
+
+```scss
+html[data-theme="cafe"] {
+  --global-bg-color: #2a1d16;
+  --global-card-bg-color: #34251d;
+  --global-text-color: #f4e8da;
+  --global-text-color-light: #c8ad94;
+  --global-theme-color: #d39a5f;
+  --global-hover-color: #d39a5f;
+  --global-divider-color: rgba(211, 154, 95, 0.28);
+}
+```
+
+Adding a fifth switcher mode is a core-theme change: extend `assets/js/theme.js`, the header toggle icons and the Sass selectors together. For normal child sites, override `light`, `cafe` or `dark` with `_sass/_site-custom.scss` instead.
+
+## JavaScript Event
+
+Local scripts can observe theme changes:
+
+```js
+document.addEventListener("unaltraweb:themechange", (event) => {
+  console.log(event.detail.theme, event.detail.themeSetting);
+});
+```
+
+## Diagram Surfaces
+
+Manual Mermaid figures receive diagram surfaces tuned for light, coffee and dark modes. Keep source diagrams simple and let the render pipeline generate theme-compatible SVGs.
+
+## Testing Themes
+
+The template Playwright smoke test reloads pages with each theme in local storage and checks the resulting attributes and CSS variables.
+
+```bash
+make test SITE_PROFILE=unaltreselfie
+make screenshots
+```
+
+Screenshots generated by `make screenshots` are copied into `assets/img/screenshots/` with `make docs-screenshots`.

data/docs/_documentation/en/22-feature-reference.md

@@ -0,0 +1,56 @@
+---
+title: Feature Reference
+description: Map of reusable unaltraweb features, syntax and examples.
+lang: en
+ref: feature_reference
+profiles:
+- unaltredocs
+documentation_profiles:
+- site-designers
+- contributors
+- core-developers
+section: Design And Customize
+weight: 340
+permalink: "/features/"
+nav_title: Feature Reference
+---
+<p class="lede">This page maps reusable <code>unaltraweb</code> features to the documentation pages and template examples that demonstrate them.</p>
+
+The companion `unaltraweb-template` repository contains full-profile demos because it exercises the core as a real child site. This site is the `unaltraweb` reference: it explains the platform and shows the syntax users should copy.
+
+## Covered Now
+
+- **Profiles**: `unaltreselfie`, `unaltreprojecte`, `unaltremanual` and `unaltredocs` are documented conceptually.
+- **Distribution**: gem, Docker image, template repository and reusable workflow responsibilities are documented.
+- **Customization**: local Sass, layouts, feature gates, manual syntax, project resources, CV previews, theme modes and developer mode have starter examples.
+
+## Feature Map
+
+| Feature | Where documented | Where demonstrated |
+|---|---|---|
+| Profiles and feature flags | [Profiles]({{ '/profiles/' | relative_url }}), [Usage]({{ '/usage/' | relative_url }}) | Template home pages and localized navigation |
+| Tools and local runtime | [Tools]({{ '/tools/' | relative_url }}), [Quick Start]({{ '/quick-start/' | relative_url }}) | Template Makefile and Docker Compose files |
+| Callouts, figures, tables and Mermaid | [Syntax]({{ '/syntax/' | relative_url }}), [Customization]({{ '/customization/' | relative_url }}) | Template manual and project resource pages |
+| Theme modes | [Themes]({{ '/themes/' | relative_url }}) | Template Playwright screenshots for light, coffee and dark modes |
+| Bibliometrics | [Bibliometrics]({{ '/bibliometrics/' | relative_url }}) | Template publications pages and metrics workflow wrapper |
+| Deployment and updates | [Distribution]({{ '/distribution/' | relative_url }}), [Development]({{ '/development/' | relative_url }}) | Reusable workflows and Dependabot configuration |
+
+## Still To Complete
+
+- Add rendered examples for every syntax item above inside this `unaltraweb` reference site.
+- Add a compact front matter reference for pages, posts, projects, chapters, documentation pages, outputs, books, theses and bibliography entries.
+- Add a data-file reference for `_data/` files used by team, repositories, metrics, readings and profile-specific pages.
+- Add profile-specific checklists for creating real sites from the template.
+- Add screenshots or visual examples for the four profiles without duplicating the full template demo.
+- Keep future `keep`/`sync` behavior separate from the existing offline distribution `doctor`; document migrations only when those commands exist.
+- Expand manual/PDF guidance once printable manual output becomes a first-class target.
+
+## Where To Look Today
+
+- [Customization](../customization/) contains most current syntax examples.
+- [Content syntax](../syntax/) contains copyable examples for syntax beyond standard Markdown.
+- [Themes](../themes/) documents theme modes and local CSS/JS integration.
+- [Site profiles](../profiles/) documents the four prepared website families.
+- [Quick start](../quick-start/) covers GitHub-only and local Docker workflows.
+- [Distribution model](../distribution/) explains gem, Docker and template responsibilities.
+- `unaltraweb-template` contains the current full-profile demo content and Playwright screenshots.

data/docs/_documentation/en/23-front-matter.md

@@ -0,0 +1,51 @@
+---
+title: Front Matter Reference
+description: Common front matter keys used by unaltraweb pages and collections.
+lang: en
+ref: front_matter_reference
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Reference
+weight: 900
+permalink: "/front-matter/"
+nav_title: Front Matter
+---
+Common keys:
+
+| Key | Purpose |
+|---|---|
+| `layout` | Selects the reusable layout. |
+| `title` | Page or document title. |
+| `description` | Summary used by cards, search and metadata. |
+| `lang` | Content language. |
+| `ref` | Stable cross-language identity. |
+| `permalink` | Public URL. |
+| `profiles` | Profiles where the item is rendered. |
+| `feature` | Feature flag controlling navigation. |
+| `nav`, `nav_order`, `nav_title` | Top navigation controls. |
+| `section`, `weight` | Documentation sidebar controls. |
+| `documentation_profiles` | Optional `unaltredocs` reader profiles that should include the page. |
+| `introduced_in`, `changed_in`, `deprecated_in`, `removed_in` | Optional version annotations for documentation pages. |
+| `hero` | Page or project hero image configuration. |
+
+Example:
+
+```yaml
+---
+title: Installation
+description: Local Docker workflow for contributors.
+lang: en
+ref: installation
+profiles: [unaltredocs]
+section: User guides
+weight: 30
+documentation_profiles: [local-authors]
+permalink: /installation/
+---
+```

data/docs/_documentation/en/24-data-files.md

@@ -0,0 +1,28 @@
+---
+title: Data Files Reference
+description: Structured data files commonly used by unaltraweb child sites.
+lang: en
+ref: data_files_reference
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Reference
+weight: 910
+permalink: "/data-files/"
+nav_title: Data Files
+---
+Use `_data/` for structured content that should not live inside prose pages.
+
+| File | Typical use |
+|---|---|
+| `_data/i18n/*.yml` | Interface labels and local translations. |
+| `_data/metrics.yml` | Generated publication metrics summary. |
+| `_data/metrics-overrides.yml` | Manual metric corrections. |
+| `_data/repositories.yml` | Repository cards and links. |
+| `_data/team.yml` or local equivalents | Team members for project pages. |
+
+Keep generated data reviewable. Metrics workflows should commit versionable outputs such as `_data/metrics.yml`, not local caches.