Documentation Index

This note maps the documentation base by subject. Each entry links to a dedicated note, and the glossary defines the technical terms that recur across notes. The notes assume a working Hugo site built with PKB-theme: content creation and theme machinery first, then deployment, then the self-hosted services (analytics, ecommerce) the theme integrates with.

Hugo and theme development

• How the Hugo System Works (2026-07-29): the dated architecture reference for the whole setup: version floor, module and config model, templates, content pipeline, and CI.
• Creating Posts with Hugo: the content workflow, from archetypes and front matter to page bundles.
• Quarto Basics with PKB Theme: authoring and publishing Quarto documents, with the Quarto Test Sample showing a rendered .qmd page.
• Hugo SEO Implementation Guide: the meta tags, Open Graph, JSON-LD, and sitemap machinery built into the theme.
• Development Tips: day-to-day practices for working on the theme itself.
• SOTA: Hugo Static Site Generator: a fully sourced survey of Hugo through v0.164.0, with an upgrade plan grounded against this theme.

Deployment and hosting

• Hosting Your Hugo Site: hosting-platform comparison and deployment steps.
• Setting up GitHub Pages: first-time GitHub Pages setup for a Hugo site.
• GitHub Pages with Hugo: the Hugo-specific CI build and deploy pipeline.
• Deploying with exampleSite: using the bundled exampleSite as a deployment template.

Analytics

• Self-Hosted Analytics for PKB-theme: choosing and wiring a privacy-friendly analytics backend.
• Analytics Configuration: the theme’s analytics params and supported providers.
• Matomo Analytics Setup Guide: a full Matomo self-hosting walkthrough.
• Reverse Proxy Configuration for Analytics: serving analytics first-party through your own domain.

Ecommerce

• Self-Hosted Ecommerce Solutions: comparison of the store platforms the notes integrate.
• OpenCart Integration Guide: connecting an OpenCart store to the theme.
• PrestaShop Integration Guide: connecting a PrestaShop store to the theme.
• Saleor Integration Guide: connecting a Saleor storefront to the theme.

Theme components

• Color Theme Customization: overriding the theme’s color schemes.
• Gallery Slider Documentation: the gallery-slider shortcode and its options.
• Portfolio Usage: the portfolio content type and its templates (draft, unpublished).
• Text to Speech: the browser-native read-aloud feature and its voice strategy.

This guide covers all the ways you can style and customize codeblocks in the PKB theme, from basic syntax highlighting to advanced features like line numbers and copy buttons.

Basic Syntax Highlighting

The theme supports syntax highlighting for numerous programming languages. Simply specify the language after the opening triple backticks:

function greet(name) {
    console.log(`Hello, ${name}!`);
}

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}

Inline Code

Use single backticks for inline code: const variable = "value" or git commit -m "message".

The Gallery Slider component provides an elegant way to display multiple images with navigation controls, thumbnails, and captions. This guide covers everything from basic usage to advanced customization.

File Organization for Images

Understanding how to organize your images is crucial for effective gallery management:

Hugo Site Structure
├── static/
│   └── images/
│       ├── docs/
│       │   └── gallery-slider-doc/
│       │       ├── landscape-1.jpg
│       │       ├── landscape-2.jpg
│       │       ├── portrait-1.jpg
│       │       └── thumb-landscape-1.jpg  ← Optional thumbnails
│       ├── gallery/
│       │   ├── nature/
│       │   │   ├── forest-1.jpg
│       │   │   └── forest-2.jpg
│       │   └── architecture/
│       │       ├── building-1.jpg
│       │       └── building-2.jpg
│       └── posts/
│           └── my-post/
│               ├── hero.jpg
│               └── detail.jpg
├── content/
│   └── posts/
│       └── my-gallery-post.md  ← Your content file
└── layouts/
    └── partials/
        └── gallery-slider.html  ← Component template

URL Structure

• Local images: /images/docs/gallery-slider-doc/landscape-1.jpg
• Web images: https://example.com/image.jpg
• Relative paths: Always start with / for Hugo static files

Basic Gallery Usage

Simple Image Gallery

Here’s a basic gallery with local images:

This document demonstrates all standard Markdown features along with proper sidenote usage. This resource is the central reference for all content creators building a Digital Garden or implementing the Zettelkasten Method.

Basic Typography

Effective typography forms the foundation of digital writing. As explained by ^11., consistent formatting improves readability. Recent studies ^22. show that proper formatting significantly impacts user engagement. As demonstrated in previous research ², this approach has been validated multiple times.

Hugo provides a powerful content creation system using archetypes and the hugo new command. This guide explains how to create different types of content in your PKB-theme site.

Understanding Hugo’s Content Structure

Hugo organizes content in sections, which correspond to directories under content/. The PKB-theme supports several content types:

• Posts (content/posts/) - Blog articles and regular content
• Docs (content/docs/) - Documentation and guides
• Pages (content/about.md) - Static pages like About, Contact

The hugo new Command

The basic syntax for creating new content is:

Quarto is an open-source scientific and technical publishing system that works in HUGO. This guide covers everything you need to know to create/display code outputs from code using a Quarto as integration.

What is Quarto?

Quarto enables you to weave together content and executable code into a finished document. It supports:

• Multiple languages: Python, R, Julia, Observable JS
• Multiple formats: HTML, PDF, MS Word, presentations, websites
• Interactive elements: Plots, widgets, and dynamic content
• Academic features: Citations, cross-references, equations

Installation and Setup

1. Install Quarto

Download and install Quarto from quarto.org:

Understanding Quarto metadata is crucial for creating well-structured, properly configured documents that integrate seamlessly with the PKB theme. Take into account that to adequately deploy a site with this HUGO, other steps are necessary. This guide covers everything from basic YAML syntax to advanced configuration options for the qmd metadata necessary as a first step.

What is Quarto Metadata?

Quarto metadata is defined in YAML format at the beginning of your document, enclosed between triple dashes (---). It controls:

Development Tips

Serving exampleSite

For theme development, use this command to serve the exampleSite with debug options:

hugo server \
  --source exampleSite \  # Point to exampleSite directory
  --noHTTPCache \         # Disable HTTP caching
  --renderToMemory \      # Render to memory
  --disableFastRender \   # Disable fast render
  --ignoreCache \         # Ignore cache
  --gc \                  # Run garbage collection
  --logLevel debug \      # Set debug log level
  -D                      # Include draft posts

Command Explanation

• --source exampleSite: Serves the example site instead of the main project
• --noHTTPCache: Prevents browser caching during development
• --renderToMemory: Renders pages in memory for faster development
• --disableFastRender: Forces full re-render of changed pages
• --ignoreCache: Ignores the cache when rebuilding
• --gc: Runs garbage collection after builds
• --logLevel debug: Shows detailed debug information
• -D: Includes draft content

Local Testing

For production testing, remove debug flags:

Deploying to GitHub Pages with Hugo

This guide explains how to deploy your PKB-theme site to GitHub Pages using Hugo’s built-in capabilities.

Prerequisites

• Hugo Extended version installed
• Git repository initialized
• GitHub account
• PKB-theme installed as a submodule

Configuration Steps

1. Update config.toml

   baseURL = "https://username.github.io/repository-name/"
   theme = "PKB-theme"
   publishDir = "docs"  # Required for GitHub Pages
   

2. Create GitHub Workflow Create .github/workflows/hugo.yml:

   name: Deploy Hugo site
   
   on:
     push:
       branches:
         - main
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
           with:
             submodules: true
             fetch-depth: 0
   
         - name: Setup Hugo
           uses: peaceiris/actions-hugo@v2
           with:
             hugo-version: 'latest'
             extended: true
   
         - name: Build
           run: hugo --minify
   
         - name: Deploy
           uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./public
   

Repository Settings

1. Go to repository Settings → Pages
2. Set Source to:
   • Deploy from a branch
   • Branch: gh-pages (created by the workflow)
   • Folder: / (root)

Local Testing

# Build site
hugo

# Test locally
hugo server

# Deploy changes
git add .
git commit -m "Update site content"
git push origin main

Troubleshooting

Common issues and solutions:

Deploying with exampleSite

The PKB-theme includes an exampleSite directory that serves as both a demo and a template for your own site.

Quick Start

1. Copy exampleSite Contents

   cp -r themes/PKB-theme/exampleSite/* .
   

2. Update Configuration Edit config.toml:

   baseURL = "https://your-username.github.io/your-site/"
   title = "Your Site Title"
   theme = "PKB-theme"
   

3. Customize Content

   • Modify content in content/ directory
   • Update images in static/ directory
   • Adjust layouts in layouts/ if needed

Directory Structure

The exampleSite provides a complete structure:

exampleSite/
├── config.toml      # Site configuration
├── content/         # Your content
│   ├── docs/        # Documentation pages
│   └── posts/       # Blog posts
├── static/          # Static assets
└── layouts/         # Custom layouts (optional)

Configuration Reference

Key settings in config.toml:

Setting up GitHub Pages with PKB-theme

This guide explains how to set up GitHub Pages for your PKB-theme repository.

Important Files

• _config.yml - Main Jekyll configuration file
• Gemfile - Ruby dependencies for GitHub Pages
• index.md - Your homepage content
• _layouts/ - Theme layout files
• assets/ - Static files like CSS, images, etc.

Setup Steps

1. Configure _config.yml

   • Ensure your _config.yml has the correct theme settings:

   remote_theme: username/PKB-theme
   

2. Enable GitHub Pages

Analytics Configuration for PKB-theme

This document describes how to configure various self-hosted analytics options for your PKB-theme website.

Available Analytics Providers

PKB-theme supports the following privacy-focused analytics providers:

• Matomo (formerly Piwik)
• Plausible
• Umami
• Fathom Lite
• Shynet

Configuration

Add the following to your config.toml or hugo.toml file:

[params.analytics]
  # Uncomment and configure the analytics system you want to use
  
  # Matomo Analytics
  # matomo = true
  # matomoSiteId = "1"
  # matomoURL = "https://analytics.yourdomain.com/"
  
  # Plausible Analytics
  # plausible = true
  # plausibleDomain = "yourdomain.com"
  # plausibleScriptSrc = "https://plausible.io/js/script.js"
  
  # Umami Analytics
  # umami = true
  # umamiWebsiteId = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  # umamiScriptSrc = "https://analytics.yourdomain.com/umami.js"
  
  # Fathom Analytics
  # fathom = true
  # fathomSiteId = "ABCDEFGH"
  # fathomScriptSrc = "https://cdn.usefathom.com/script.js"
  
  # Shynet Analytics
  # shynet = true
  # shynetURL = "https://analytics.yourdomain.com"
  # shynetUUID = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

Detailed Installation Guides

For detailed installation instructions, refer to these content pages:

Matomo Analytics for PKB-theme

This guide provides detailed instructions for integrating Matomo Analytics with your PKB-theme. Matomo is a powerful, privacy-focused alternative to Google Analytics that gives you complete control over your data.

Why Choose Matomo?

Matomo (formerly Piwik) offers several advantages:

• Full data ownership: All data stays on your server
• Privacy compliance: Built-in GDPR, CCPA, and cookie law compliance tools
• Feature parity: Similar features to Google Analytics
• No data limits: Analyze unlimited websites and users
• Customizable: Extensive API and plugin system

Installation Options

Option 1: Docker Installation (Recommended)

1. Create a docker-compose.yml file:

flowchart TB
 subgraph subGraph0["PKB-theme Project"]
        PKB["/home/gespitia/projects/PKB-theme/"]
        CONFIG_TOML["config/_default/hugo.toml<br>🔧 Analytics Configuration"]
        SEO_YML["data/seo.yml<br>🚀 Performance Config"]
  end
 subgraph subGraph1["Core Docker Configuration"]
        DOCKER_COMPOSE["docker-compose.yml<br>🐳 Container Orchestration"]
        DOCKER_OVERRIDE["docker-compose.override.yml<br>🔧 Development Overrides"]
        ENV_FILE[".env<br>🔐 Environment Variables"]
  end
 subgraph subGraph2["Database Configuration"]
        POSTGRES_CONF["postgresql.conf<br>🗄️ Database Tuning"]
        POSTGRES_INIT["postgres-init/01-init.sql<br>📊 Database Setup"]
  end
 subgraph subGraph3["Cache Configuration"]
        REDIS_CONF["redis.conf<br>⚡ Cache Settings"]
  end
 subgraph subGraph4["Backup & Monitoring"]
        BACKUP_SCRIPT["backup-script.sh<br>💾 Database Backup"]
        BACKUP_CLEANUP["backup-cleanup.sh<br>🧹 Cleanup Script"]
        MONITOR_SCRIPT["monitor-matomo.sh<br>📊 Health Check"]
  end
 subgraph subGraph5["Runtime Directories (Auto-created)"]
        CONFIG_DIR["config/<br>📁 Matomo Config"]
        LOGS_DIR["logs/<br>📋 Application Logs"]
        PLUGINS_DIR["plugins/<br>🔌 Custom Plugins"]
        BACKUPS_DIR["backups/<br>💾 Database Backups"]
  end
 subgraph subGraph6["Existing Config Files"]
        MATOMO_CONFIG["config/config.ini.php<br>⚙️ Matomo Settings (Auto-generated)"]
        GLOBAL_CONFIG["config/global.ini.php<br>📋 Global Settings (Read-only)"]
        PLUGIN_CONFIGS["plugins/*/config/<br>🔌 Plugin Configurations"]
  end
 subgraph subGraph7["Matomo Analytics Project"]
        MATOMO_ROOT["/home/gespitia/projects/matomo-analytics/"]
        subGraph1
        subGraph2
        subGraph3
        subGraph4
        subGraph5
        subGraph6
  end
 subgraph subGraph8["System Configuration (Optional)"]
        NGINX_CONF["nginx-analytics.conf<br>🌐 Reverse Proxy"]
        SYSTEM_NGINX["/etc/nginx/sites-available/<br>📁 System Nginx Config"]
        SYSTEMD_SERVICE["/etc/systemd/system/matomo-docker.service<br>🔄 Auto-start Service"]
        CRON_JOBS["/etc/cron.d/matomo<br>⏰ Scheduled Tasks"]
  end
 subgraph subGraph9["Project Structure Overview"]
        subGraph0
        subGraph7
        subGraph8
  end

    PKB --> CONFIG_TOML & SEO_YML
    MATOMO_ROOT --> DOCKER_COMPOSE & DOCKER_OVERRIDE & ENV_FILE & POSTGRES_CONF & POSTGRES_INIT & REDIS_CONF & BACKUP_SCRIPT & BACKUP_CLEANUP & MONITOR_SCRIPT
    MATOMO_ROOT -.-> CONFIG_DIR & LOGS_DIR & PLUGINS_DIR & BACKUPS_DIR
    CONFIG_DIR --> MATOMO_CONFIG & GLOBAL_CONFIG
    PLUGINS_DIR --> PLUGIN_CONFIGS
    NGINX_CONF -.-> SYSTEM_NGINX
    ENV_FILE -.-> DOCKER_COMPOSE
    POSTGRES_CONF -.-> DOCKER_COMPOSE
    REDIS_CONF -.-> DOCKER_COMPOSE
    BACKUP_SCRIPT -.-> DOCKER_COMPOSE & CRON_JOBS
    BACKUP_CLEANUP -.-> DOCKER_COMPOSE
    POSTGRES_INIT -.-> DOCKER_COMPOSE
    CONFIG_TOML -.-> NGINX_CONF
    NGINX_CONF -.-> SYSTEMD_SERVICE
    MONITOR_SCRIPT -.-> CRON_JOBS
    
     CONFIG_TOML:::pkb
     SEO_YML:::pkb
     DOCKER_COMPOSE:::coreConfig
     DOCKER_OVERRIDE:::coreConfig
     ENV_FILE:::coreConfig
     POSTGRES_CONF:::dbConfig
     POSTGRES_INIT:::dbConfig
     REDIS_CONF:::cacheConfig
     BACKUP_SCRIPT:::monitoring
     BACKUP_CLEANUP:::monitoring
     MONITOR_SCRIPT:::monitoring
     CONFIG_DIR:::runtime
     LOGS_DIR:::runtime
     PLUGINS_DIR:::runtime
     BACKUPS_DIR:::runtime
     MATOMO_CONFIG:::existing
     GLOBAL_CONFIG:::existing
     PLUGIN_CONFIGS:::existing
     NGINX_CONF:::system
     SYSTEMD_SERVICE:::system
     CRON_JOBS:::system
     
    classDef coreConfig fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef dbConfig fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef cacheConfig fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef monitoring fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef runtime fill:#fce4ec,stroke:#880e4f,stroke-width:2px
    classDef existing fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    classDef system fill:#fff8e1,stroke:#f57f17,stroke-width:2px
    classDef pkb fill:#e0f2f1,stroke:#00695c,stroke-width:2px

Diagram Internet to files

flowchart TB

Here are the suggested file locations and names for each configuration:

Self-Hosted Analytics for PKB-theme

This guide helps you implement visitor analytics for your PKB-theme using privacy-respecting, FOSS (Free and Open Source Software) solutions. Unlike commercial analytics platforms that collect excessive data and track users across sites, these tools focus on essential metrics while respecting user privacy.

Analytics Solutions Comparison

*Shynet can use tracking pixels instead of JavaScript