Customize A Child Site

Local customization points for unaltraweb child sites.

unaltraweb is intended to be customized from the site repository, not by editing the core theme files.

Local Styles

Create _sass/_site-custom.scss in your site repository. It is imported after the core styles, so local rules can override CSS custom properties or add small components while still receiving upstream unaltraweb updates.

:root {
  --global-theme-color: #2f6f5e;
  --global-hover-color: #2f6f5e;
}

html[data-theme="cafe"] {
  --global-theme-color: #6f4e1f;
}

The built-in coffee mode uses data-theme="cafe". Override CSS custom properties in that selector when you want a different brown palette without changing light or dark mode.

For larger local style changes, keep selectors scoped by profile or theme:

html[data-site-profile="unaltredocs"] .documentation-sidebar {
  --documentation-toc-line: color-mix(in srgb, var(--global-theme-color) 42%, var(--global-divider-color));
}

html[data-theme="dark"] .my-local-card {
  background: #1f2935;
}

Do not copy _sass/ files from unaltraweb into a child site. Override tokens and small selectors locally so future gem updates still apply.

Multilingual Hyphenation

Text hyphenation is enabled globally in the main content area. Browsers use the page language from lang (en, es, ca, or another configured language) to choose the hyphenation dictionary.

Use .no-hyphenate when a specific word, brand, code-like label or compact block should not be split:

<span class="no-hyphenate">dosquartsdedocs</span>

For mixed-language passages, set the appropriate lang attribute on the local element so the browser can switch dictionaries.

Local Layouts

Create a layout in _layouts/ inside the site repository and reference it from page front matter.

---
layout: page
---

<div class="my-local-layout">
  








<script>
  window.unaltrawebContentSearchUrl = "/unaltraweb/assets/js/documentation-search-index.json";
  window.unaltrawebContentSearchTarget = ".documentation-content";
</script>

<div class="documentation-layout">
  

















<aside class="documentation-sidebar" aria-label="Table of contents">
  <button class="documentation-tool-button documentation-toc-toggle" type="button" data-documentation-sidebar-toggle aria-controls="documentation-nav" aria-expanded="true" title="Show or hide table of contents">
    <i class="ti ti-chevrons-left" aria-hidden="true"></i>
    <span class="documentation-tool-label">Table of contents</span>
    <span class="sr-only">Show or hide table of contents</span>
  </button>

  <div class="documentation-sidebar-inner">

    <nav id="documentation-nav" class="documentation-nav has-profile-selector" aria-label="Table of contents">
      

      
        <div class="documentation-nav-block documentation-profile-switcher" data-documentation-profile-switcher>
          <label class="documentation-profile-label" for="documentation-profile-select">Documentation profile</label>
          <div class="documentation-profile-control">
            <span class="documentation-profile-icon" aria-hidden="true"><i class="ti ti-users"></i></span>
            <select id="documentation-profile-select" class="documentation-profile-select" data-documentation-profile-select>
              <option value="">All documentation</option>
              
                
                
                <option value="github-publishers">GitHub publishers</option>
              
                
                
                <option value="local-authors">Local authors</option>
              
                
                
                <option value="site-designers">Site designers</option>
              
                
                
                <option value="contributors">Contributors</option>
              
                
                
                <option value="core-developers">Core developers</option>
              
            </select>
          </div>
        </div>
      

      <div class="documentation-nav-block documentation-toc-heading-block">
        <p class="documentation-nav-block-title">Table of contents</p>
      </div>

      <div class="documentation-nav-scroll">
        <div class="documentation-overview-section">
          <a class="documentation-overview-link" href="/unaltraweb/">
            <span class="documentation-overview-icon" aria-hidden="true"><i class="ti ti-home"></i></span>
            Overview
          </a>
        </div>

        <div class="documentation-accordion documentation-docs-block" data-documentation-tree>
          
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-start-here">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Start Here</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/quick-start/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Start Here
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-publish-with-github">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Publish With GitHub</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/reusable-workflows/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,contributors,core-developers"
>
                      GitHub Workflows
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-work-locally">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Work Locally</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/tools/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,contributors,core-developers"
>
                      Local Tools
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/usage/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,site-designers,contributors,core-developers"
>
                      Run And Preview
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/jekyll-basics/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,site-designers,contributors,core-developers"
>
                      Jekyll Basics
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/docker-image/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,core-developers"
>
                      Docker Image
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-build-a-site">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Build A Site</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/pages-collections-navigation/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Pages And Navigation
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Site Profiles
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/unaltreselfie/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors"
>
                      Personal Site
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/unaltreprojecte/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors"
>
                      Project Site
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/unaltremanual/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Manual Site
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/unaltredocs/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Documentation Portal
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/profiles/checklist/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Feature Checklist
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-design-and-customize" data-documentation-active-section="true" open>
              <summary class="documentation-accordion-summary active">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Design And Customize</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/syntax/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors"
>
                      Markdown Extensions
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2 active" href="/unaltraweb/themes/" aria-current="page"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,site-designers,contributors"
>
                      Themes
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/customization/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,site-designers,contributors,core-developers"
>
                      Customization
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/features/"

 data-documentation-profile-item
 data-documentation-profiles="site-designers,contributors,core-developers"
>
                      Feature Reference
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-contribute">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Contribute</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/template/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,contributors,core-developers"
>
                      Core And Template
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-core-development">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Core Development</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/development/"

 data-documentation-profile-item
 data-documentation-profiles="contributors,core-developers"
>
                      Core Development
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/distribution/"

 data-documentation-profile-item
 data-documentation-profiles="core-developers"
>
                      Distribution Model
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/bibliometrics/"

 data-documentation-profile-item
 data-documentation-profiles="contributors,core-developers"
>
                      Metrics Pipeline
                    </a>
                  
                
              </div>
            </details>
          
            
            
            
            
            <details class="documentation-accordion-section" data-documentation-tree-id="section-reference">
              <summary class="documentation-accordion-summary">
                <span class="documentation-accordion-mark" aria-hidden="true"></span>
                <span class="documentation-accordion-title">Reference</span>
                <span class="documentation-accordion-caret" aria-hidden="true"><i class="ti ti-chevron-down"></i></span>
              </summary>
              <div class="documentation-accordion-items">
                
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/front-matter/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      Front Matter
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/data-files/"

 data-documentation-profile-item
 data-documentation-profiles="local-authors,site-designers,contributors,core-developers"
>
                      Data Files
                    </a>
                  
                
                  
                  
                    
                    <a class="documentation-nav-link documentation-accordion-link level-2" href="/unaltraweb/faq/"

 data-documentation-profile-item
 data-documentation-profiles="github-publishers,local-authors,site-designers,contributors,core-developers"
>
                      FAQ
                    </a>
                  
                
              </div>
            </details>
          
        </div>
      </div>
    </nav>
  </div>
</aside>

  
<aside class="documentation-section-toc" data-documentation-page-toc-container hidden aria-label="On this page">
  <div class="documentation-section-toc-inner">
    <p class="documentation-section-toc-heading">On this page</p>
    <nav class="documentation-section-toc-nav" aria-label="On this page">
      <ol class="documentation-section-toc-list" data-documentation-page-toc></ol>
    </nav>
  </div>
</aside>


  <article class="documentation-main documentation-page" data-documentation-current-page


 data-documentation-profiles="local-authors,site-designers,contributors"
>
    <header class="documentation-page-header">
      
        <nav class="documentation-breadcrumb" aria-label="Documentation location">
          <span class="documentation-breadcrumb-item">Design And Customize</span>
          
        </nav>
      
      <h1>Theme And Visual Design</h1>
      <p class="documentation-subtitle">Theme modes, local style overrides and JavaScript integration in unaltraweb.</p>
      <div class="documentation-profile-notice" data-documentation-profile-notice hidden>This page is outside the active documentation profile, but direct links remain available.</div>
    </header>

    <div class="documentation-content">
      <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>

<h2 id="modes">Modes</h2>

<ul>
  <li><strong>Light</strong>: high-contrast default reading mode for normal pages and profile sites.</li>
  <li><strong>Coffee</strong>: warm brown reading mode for manuals, long-form documentation and course material.</li>
  <li><strong>Dark</strong>: dark mode with matching integration state for embedded libraries and generated diagrams.</li>
</ul>

<p>The switch rotates through:</p>

<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>system -&gt; light -&gt; coffee -&gt; dark -&gt; system
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">system</code> follows the browser preference and resolves to light or dark.</p>

<h2 id="data-attributes">Data Attributes</h2>

<p>The active theme state is exposed on <code class="language-plaintext highlighter-rouge">&lt;html&gt;</code>:</p>

<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;html</span> <span class="na">data-theme-setting=</span><span class="s">"cafe"</span> <span class="na">data-theme=</span><span class="s">"cafe"</span> <span class="na">data-theme-integration=</span><span class="s">"light"</span> <span class="na">data-site-profile=</span><span class="s">"unaltremanual"</span><span class="nt">&gt;</span>
</code></pre></div></div>

<p>Use these attributes for local CSS and automated checks. Do not infer the active profile from URLs.</p>

<h2 id="local-sass-overrides">Local Sass Overrides</h2>

<p>Create <code class="language-plaintext highlighter-rouge">_sass/_site-custom.scss</code> in the child site. It is imported after the core styles.</p>

<div class="language-scss highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">:root</span> <span class="p">{</span>
  <span class="na">--global-theme-color</span><span class="p">:</span> <span class="mh">#2f6f5e</span><span class="p">;</span>
  <span class="na">--global-hover-color</span><span class="p">:</span> <span class="mh">#2f6f5e</span><span class="p">;</span>
<span class="p">}</span>

<span class="nt">html</span><span class="o">[</span><span class="nt">data-theme</span><span class="o">=</span><span class="s2">"cafe"</span><span class="o">]</span> <span class="p">{</span>
  <span class="na">--global-theme-color</span><span class="p">:</span> <span class="mh">#6f4e1f</span><span class="p">;</span>
<span class="p">}</span>

<span class="nt">html</span><span class="o">[</span><span class="nt">data-site-profile</span><span class="o">=</span><span class="s2">"unaltremanual"</span><span class="o">]</span> <span class="nc">.manual-sidebar</span> <span class="p">{</span>
  <span class="nl">border-color</span><span class="p">:</span> <span class="nf">var</span><span class="p">(</span><span class="o">--</span><span class="n">global-theme-color</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<h2 id="custom-coffee-palette">Custom Coffee Palette</h2>

<p>Use CSS custom properties to customize a built-in mode without changing the theme switcher:</p>

<div class="language-scss highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">html</span><span class="o">[</span><span class="nt">data-theme</span><span class="o">=</span><span class="s2">"cafe"</span><span class="o">]</span> <span class="p">{</span>
  <span class="na">--global-bg-color</span><span class="p">:</span> <span class="mh">#2a1d16</span><span class="p">;</span>
  <span class="na">--global-card-bg-color</span><span class="p">:</span> <span class="mh">#34251d</span><span class="p">;</span>
  <span class="na">--global-text-color</span><span class="p">:</span> <span class="mh">#f4e8da</span><span class="p">;</span>
  <span class="na">--global-text-color-light</span><span class="p">:</span> <span class="mh">#c8ad94</span><span class="p">;</span>
  <span class="na">--global-theme-color</span><span class="p">:</span> <span class="mh">#d39a5f</span><span class="p">;</span>
  <span class="na">--global-hover-color</span><span class="p">:</span> <span class="mh">#d39a5f</span><span class="p">;</span>
  <span class="na">--global-divider-color</span><span class="p">:</span> <span class="nf">rgba</span><span class="p">(</span><span class="m">211</span><span class="o">,</span> <span class="m">154</span><span class="o">,</span> <span class="m">95</span><span class="o">,</span> <span class="m">0</span><span class="mi">.28</span><span class="p">);</span>
<span class="p">}</span>
</code></pre></div></div>

<p>Adding a fifth switcher mode is a core-theme change: extend <code class="language-plaintext highlighter-rouge">assets/js/theme.js</code>, the header toggle icons and the Sass selectors together. For normal child sites, override <code class="language-plaintext highlighter-rouge">light</code>, <code class="language-plaintext highlighter-rouge">cafe</code> or <code class="language-plaintext highlighter-rouge">dark</code> with <code class="language-plaintext highlighter-rouge">_sass/_site-custom.scss</code> instead.</p>

<h2 id="javascript-event">JavaScript Event</h2>

<p>Local scripts can observe theme changes:</p>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">document</span><span class="p">.</span><span class="nf">addEventListener</span><span class="p">(</span><span class="dl">"</span><span class="s2">unaltraweb:themechange</span><span class="dl">"</span><span class="p">,</span> <span class="p">(</span><span class="nx">event</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
  <span class="nx">console</span><span class="p">.</span><span class="nf">log</span><span class="p">(</span><span class="nx">event</span><span class="p">.</span><span class="nx">detail</span><span class="p">.</span><span class="nx">theme</span><span class="p">,</span> <span class="nx">event</span><span class="p">.</span><span class="nx">detail</span><span class="p">.</span><span class="nx">themeSetting</span><span class="p">);</span>
<span class="p">});</span>
</code></pre></div></div>

<h2 id="diagram-surfaces">Diagram Surfaces</h2>

<p>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.</p>

<h2 id="testing-themes">Testing Themes</h2>

<p>The template Playwright smoke test reloads pages with each theme in local storage and checks the resulting attributes and CSS variables.</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>make <span class="nb">test </span><span class="nv">SITE_PROFILE</span><span class="o">=</span>unaltreselfie
make screenshots
</code></pre></div></div>

<p>Screenshots generated by <code class="language-plaintext highlighter-rouge">make screenshots</code> are copied into <code class="language-plaintext highlighter-rouge">assets/img/screenshots/</code> with <code class="language-plaintext highlighter-rouge">make docs-screenshots</code>.</p>

    </div>

    
  </article>
</div>

</div>

---
layout: my-local-layout
title: Custom Page
---

Jekyll resolves site files before theme files, so local layouts can extend or override core layouts without forking unaltraweb.

Site Profiles And Features

Use site.unaltraweb.site_profile to select the prepared website profile and site.unaltraweb.features to enable or hide standard sections. A site profile is a high-level preset for the kind of website being built; it is not a Jekyll layout or include.

unaltraweb:
  site_profile: unaltreselfie
  features:
    blog: true
    cv: true
    projects: true
    publications: true
    metrics: true

Navigation pages can opt into a feature gate with front matter:

---
title: Projects
ref: projects
feature: projects
nav: true
---

If unaltraweb.features.projects is false, that page is hidden from the navigation. The page still exists if it is published, so users can keep drafts or direct links while changing presets.

Standard Section Layouts

Several reusable sections are layouts. Child sites should prefer these layouts over copying Liquid loops into their pages:

---
layout: outputs
title: Outputs
ref: outputs
permalink: /en/outputs/
---

---
layout: repositories
title: Repositories
ref: repositories
permalink: /en/repositories/
---

---
layout: theses
title: Theses
ref: theses
permalink: /en/theses/
---

---
layout: book-shelf
title: Readings
ref: books
collection: books
permalink: /en/readings/
---

The content lives in the site repository: _outputs/ for output cards, _data/repositories.yml for repository cards, _theses/ for thesis records, and _books/ for reading notes. The rendering logic stays in unaltraweb.

Callout Shorthand

Use nested Markdown blockquotes for lightweight teaching callouts. A single > remains a normal quotation; deeper levels become callouts:

>> A note or tip.

>>> A worked example.

>>>> A warning.

>>>>> Learning objectives.

>>>>>> A caution or danger note.

The labels are localized through _data/i18n/*.yml under callouts, and the colors follow the active light, coffee, or dark theme.

Manual Profile

Use the unaltremanual site profile for academic handbooks, course manuals and book-like teaching material. The core profile provides a cover page, a sticky contents sidebar, a right-hand chapter table of contents, multilingual chapter routing, teacher blocks, automatic figure captions for chapters, a full-text manual search index, navbar reader font-size controls and a bibliography section without bibliometric badges.

unaltraweb:
  site_profile: unaltremanual
  manual:
    collection: chapters
    cover_image: /assets/img/manual-cover.svg
    logo: /assets/img/brand/dosquartsdedocs-logo.svg
    logo_inverse: /assets/img/brand/dosquartsdedocs-logo-white.svg
  figure_captions:
    enabled: true
    collections: [chapters]

scholar:
  # Optional, useful when porting a GitBook/TIG-style course bibliography.
  style: _bibliography/my-apa-cv-no-access.csl
  bibliography_template: manual-bib
  group_by: none

Create one localized home page per language with layout: manual-home and ref: home, then add chapters to _chapters/<lang>/:

---
layout: manual-chapter
title: Reading Spatial Data
lang: en
ref: reading-spatial-data
weight: 20
permalink: /en/chapters/reading-spatial-data/
manual_references: true
mermaid:
  enabled: true
  zoomable: true
---

Markdown images inside configured chapter collections are wrapped in <figure> elements and get localized labels. Use the optional image title as the caption:

![Digitizing workflow](/unaltraweb/assets/img/workflow.svg "Main editing steps")

For multi-panel teaching figures, use a compact subfigure block. The layout string uses / for rows and + for columns, inspired by patchwork-style composition:

::: subfigures a+b/c "Three views of the same exercise"
![Interface](/unaltraweb/assets/img/interface.svg "Interface")
![Map](/unaltraweb/assets/img/map.svg "Map")
![Diagram](/unaltraweb/assets/img/diagram.svg "Diagram")
:::

This renders one numbered figure with panel labels a, b, c; the contained images remain ordinary Markdown image declarations.

Manual chapters can also number teaching tables with the same localized counter style. Wrap a regular Markdown table in a table block and put the caption in the opening line:

::: table "Weekly work rhythm"
| Week | Focus | Output |
| --- | --- | --- |
| 1 | Orientation | Reading notes |
| 2 | Data setup | Working project folder |
:::

This renders a numbered table with localized labels such as Table 1., Taula 1. or Tabla 1.. Tables and figures keep separate counters.

Use fenced code blocks for programming examples. The theme uses Rouge, so common TIG languages such as Bash/Linux shell, Windows PowerShell, SQL/PostGIS, Python, R and Haskell get syntax highlighting when the fence includes the language name:

Inline code like `ST_Transform` stays inside the paragraph.

```sql
SELECT ST_Area(geom::geography) AS area_m2
FROM protected_areas;
```

```bash
ogrinfo data/raw/roads.gpkg -so roads
```

```powershell
ogrinfo data\raw\roads.gpkg -so roads
```

```python
import geopandas as gpd
```

```r
library(sf)
```

```haskell
manhattan :: Int -> Int -> Int
```

The manual profile also writes assets/js/manual-search-index.json during the build so the sidebar search can find terms anywhere in the localized manual.

Mermaid source references ending in .mmd are rewritten to .mmd.edited.svg when that file exists, or .mmd.svg otherwise. Manual Mermaid figures also receive diagram surfaces tuned for light, dark and coffee themes. This keeps generated diagrams and hand-edited diagrams readable in the same Markdown:

![Vector workflow](/unaltraweb/assets/diagrams/vector-workflow.mmd "Vector workflow")

Page Hero Images

Any page that uses layout: page or layout: about can define a hero image in front matter. The compact form keeps compatibility with older pages:

---
layout: page
title: Example Page
hero_image: /assets/img/example-hero.jpg
hero_image_alt: Short accessible description
hero_caption: Optional caption
hero_source: Optional source name
hero_source_url: https://example.org/source
---

For new pages, use the grouped hero form:

---
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
---

Blog Pagination

Child sites can enable blog pagination without changing the core defaults. Set pagination in the site config and enable it on the blog page that includes blog-list.liquid.

pagination:
  enabled: true
  collection: posts
  per_page: 4
  permalink: /page/:num/
  title: ":title"
  sort_field: date
  sort_reverse: true

---
title: Blog
pagination:
  enabled: true
  locale: en
---

blog-list.liquid uses paginator.posts when Jekyll generates paginated pages and falls back to the localized post archive otherwise. For multilingual sites, set the page-level pagination.locale and the same locale value in each post front matter.

Project Card Images

Project entries can define a main image with hero. In project cards, that image is used as a very light degraded background for the card.

---
title: Example Project
description: Short project summary.
hero: /assets/img/projects/example.jpg
---

Project Resources

Project entries can also define resources. These links are rendered as icon badges on the project card and in a resources panel inside pages that use layout: project.

---
layout: project
title: Example Project
resources:
  - type: zenodo
    label: Zenodo dataset
    url: https://zenodo.org/records/1000001
    doi: 10.5281/zenodo.1000001
  - type: dataset
    label: Harmonized data layers
    url: https://example.org/datasets/example
  - type: documentation
    label: Technical notes
    url: https://example.org/docs/example
---

Supported built-in icon types include zenodo, doi, dataset, data, code, github, repository, documentation, docs, unaltremanual, map, publication, paper, report, website, and link. A resource can override the icon with an explicit class, for example icon: fa-solid fa-chart-line.

CV Preview Cards

Use cv-download-card.liquid on CV pages when the PDF is the source of truth and the page should show a first-page preview plus a download button.

---
cv_pdf: /assets/pdf/cv.pdf
cv_preview: /assets/img/cv-preview.jpg
---

{% include cv-download-card.liquid pdf=page.cv_pdf preview=page.cv_preview title="CV" %}

Child sites can generate the preview with their template Makefile target:

make cv-preview CV_PDF=assets/pdf/cv.pdf CV_PREVIEW=assets/img/cv-preview.jpg

Theme Modes

The built-in theme switch supports system, light, cafe, and dark settings. system follows the browser preference and resolves to light or dark; cafe is an explicit coffee reading mode for warm long-form pages.

Theme changes are observable from JavaScript through the unaltraweb:themechange event:

document.addEventListener("unaltraweb:themechange", (event) => {
  console.log(event.detail.theme, event.detail.themeSetting);
});

The active values are also available on <html> as data-theme, data-theme-setting, data-theme-integration, and data-site-profile. These attributes are stable enough for local styles and automated browser tests.

Developer Mode

Child sites can enable unaltraweb.developer_mode in a development-only config file. When JEKYLL_ENV is not production, this displays a floating indicator showing the real profile used by the current build.

unaltraweb:
  developer_mode: true

Keep this setting out of production builds. The template Makefile writes it to tmp/_config.development.yml for make serve, while make build uses the normal production config.

Do not rely on client-side preview shells for alternate profiles. Jekyll renders one real configuration per build, so profiles should be tested by rebuilding with a config overlay, for example make serve SITE_PROFILE=unaltreprojecte in the template. Pages can declare profiles: [unaltreselfie] or profiles: [unaltreprojecte]; the core filters non-matching pages before writing the site.