How the Hugo System Works (as of 2026-07-29)

This note documents the Hugo architecture of PKB-theme as it stands today, after the alignment with Hugo v0.164.0. It is a dated snapshot: Hugo moves quickly, so check the version floor and the SOTA survey before relying on details here.

Version floor and why

The theme requires Hugo v0.164.0 (theme.toml min_version, CI pin, README). The floor is set by four features the theme now depends on: useEmbedded render-hook enums (v0.148.0), the locale config key replacing languageCode (v0.158.0), per-format imaging config plus [imaging.meta] (v0.163.0), and Chroma dark/light style pairs (v0.164.0). The v0.146 template-system rewrite shapes the entire layouts/ tree.

Glossary

Terms are listed alphabetically. Each entry gives a short definition followed by links to the notes that cover the term in depth; the glossary disambiguates, the notes explain.

Archetype: the template Hugo uses to seed a new content file created with hugo new. See Creating Posts with Hugo.

Chroma: the syntax highlighter built into Hugo; the theme drives it class-based with generated dark/light style pairs that follow the color-scheme toggle. See How the Hugo System Works, SOTA: Hugo.

SOTA: Hugo Static Site Generator

As of 2026-07-28. Mode: survey (repo-grounded against PKB-theme). Freshness: findings older than 12 months are flagged [STALE]. Every numbered claim ends with its source and access date; anything unverifiable is marked [UNVERIFIED].

TL;DR

• The latest Hugo release is v0.164.0 (2026-07-06). Roughly 25 minor releases shipped in the last 19 months; the project is very actively maintained, still centered on Bjørn Erik Pedersen.
• The big theme-author events of the period: the v0.146 template-system rewrite (new layouts/ structure), v0.148 render-hook useEmbedded enums (replacing enableDefault), the v0.156 mass removal of long-deprecated APIs, v0.158 languageCode → locale, v0.163 per-format imaging config, and v0.164 resources.PostProcess → templates.Defer.
• PKB-theme’s in-progress migration to useEmbedded = 'fallback' is correct (minimum version v0.148.0, verified). But its CI pins Hugo 0.123.7 / 0.128.0 - below the theme’s own min_version = "0.136.0" and far below the README’s new “v0.148+” claim. Aligning versions is the top action.
• Concrete code updates for this repo: replace .Page.Scratch (deprecated v0.138.0) in the cite/sidenote shortcodes, move the global imaging.quality into per-format blocks, rename languageCode → locale, and audit two non-standard render hooks (render-inline.html, render-paragraph.html) that are not part of Hugo’s documented hook set.

Landscape

Release train & maintenance

Hugo ships a minor release roughly every 3–5 weeks with patch releases in between. From v0.140.0 (2024-12-17) to v0.164.0 (2026-07-06) there were 25 minor lines, the majority of which introduced at least one deprecation or small breaking change - Hugo deprecates aggressively and removes on a ~6–18 month horizon. Maintenance is healthy but concentrated: bep accounts for ~60–68% of commits; jmooring is the most visible secondary maintainer; ~210 open issues with closure rate exceeding creation rate over the last year. License: Apache-2.0. No formal public roadmap - direction is visible via GitHub milestones (v0.165.0 is the current one). (releases, contributors, milestone 370, accessed 2026-07-28)

Polar Axis (Python)

A line plot on a polar axis.

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()

Summary Statistics (R)

Using base R to summarize the cars dataset:

summary(cars)

     speed           dist       
 Min.   : 4.0   Min.   :  2.00  
 1st Qu.:12.0   1st Qu.: 26.00  
 Median :15.0   Median : 36.00  
 Mean   :15.4   Mean   : 42.98  
 3rd Qu.:19.0   3rd Qu.: 56.00  
 Max.   :25.0   Max.   :120.00  

Histogram in R

A basic histogram using base R:

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

This is a comprehensive test post designed to showcase the various features and capabilities of the PKB theme. It includes multiple markdown elements, components, and formatting options to ensure everything renders correctly.

Introduction

Welcome to our test archetype! This post demonstrates how different content types render within the theme. From basic text formatting to complex components like tables, code blocks, and mathematical expressions^aa.Sidenotes are particularly useful for additional context without breaking the reading flow.

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:

Text-to-Speech: From Browser APIs to Voice Creation

Text-to-Speech (TTS) technology has evolved from expensive specialized hardware to ubiquitous browser-native capabilities. This comprehensive guide explores how speech synthesis works, the underlying browser APIs, and practical implementation strategies across different platforms.

How Speech is Created

The Speech Synthesis Pipeline

Modern TTS systems follow a sophisticated multi-stage process to convert text into natural-sounding speech:

Text Input → Text Analysis → Phonetic Conversion → Audio Generation → Output

1. Text Analysis and Preprocessing

• Text normalization: Converting abbreviations, numbers, dates into readable format
• Sentence segmentation: Breaking text into manageable chunks
• Token classification: Identifying proper nouns, acronyms, punctuation

2. Linguistic Analysis

• Part-of-speech tagging: Determining grammatical roles
• Prosodic analysis: Planning stress, rhythm, and intonation patterns
• Phonetic transcription: Converting words to phoneme sequences

3. Audio Synthesis Methods

Concatenative Synthesis:

When customizing a theme, readability is achieved with a contrasting color palette.

This can be easily done by having a grayscaled theme with very different grades of Luminance (eg. black background, white letters (dark theme) or vice-versa (light theme)), end of the story.

But if you want to add colors, the alternatives are more nuanced and myriad.

Firstly, make sure you have a local copy of the CSS variables:

mkdir -p assets/css/global/variables/
curl -L -o assets/css/global/variables/core.css https://github.com/stradichenko/PKB-theme/raw/main/assets/css/global/variables/core.css

We suggest the following strategy:

Zettelkasten Method

The Zettelkasten method is a powerful note-taking and knowledge management system developed by German sociologist Niklas Luhmann.

What is Zettelkasten?

Zettelkasten (German for “slip box”) is a method that emphasizes:

1. Atomic notes (one idea per note)
2. Explicit connections between notes
3. Emergent structure through links

For formatting your Zettelkasten notes, see our Markdown reference.

Core Principles

Atomic Notes

Each note should contain exactly one idea, making it easier to connect and recombine.

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

This guide covers best practices for styling your Hugo website, with a focus on knowledge base themes.

CSS Organization in Hugo

Hugo offers several approaches to CSS:

1. Resources Pipeline - Process SCSS/SASS files
2. Asset Bundling - Combine and minify CSS
3. CSS Variables - For theme customization

For markdown formatting options within your styled site, see our Markdown reference.

Theme Components

Typography

Typography forms the foundation of any knowledge base:

Digital Garden Guide

Digital gardens represent a new approach to personal websites—less blog, more evolving collection of notes and ideas. For guidance on formatting your digital garden entries, refer to our comprehensive Markdown Boilerplate.

What is a Digital Garden?

A digital garden is a collection of notes, essays, and ideas that aren’t necessarily finished or polished. Unlike blogs organized chronologically, digital gardens organize content by topic and connections.

For a broader context on knowledge management, see our Personal Knowledge Base guide. The proper formatting of your garden notes is crucial—our Markdown Boilerplate provides all the syntax examples you’ll need.

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:

Building a Personal Knowledge Base

A personal knowledge base (PKB) is a system for storing, organizing, and retrieving your knowledge and ideas. This post explains how to build one effectively.

What is a Personal Knowledge Base?

A PKB is a personalized system that helps you collect, connect, and cultivate your ideas and information. Unlike traditional note-taking, a PKB emphasizes connections between concepts.

For formatting your notes properly, refer to our Markdown tester guide.

Content Organization Guide

Effective content organization is crucial for any knowledge management system. This guide covers best practices for structuring your digital content. For proper formatting of all elements in this guide, refer to our comprehensive Markdown Boilerplate.

Hierarchical vs. Network Organization

Traditional organization is hierarchical (folders and subfolders), but knowledge bases benefit from a network approach with bidirectional links. See our Markdown Boilerplate for examples of proper linking syntax.

Academic Writing with Markdown

Academic writing requires precision, clarity, and proper citations. This guide demonstrates how Markdown can streamline the academic writing process while maintaining scholarly standards. For comprehensive syntax examples, refer to our Markdown Boilerplate.

Why Use Markdown for Academic Writing?

Traditional academic writing relies on complex word processors or LaTeX. Markdown offers a middle ground:

1. Simplicity - Focus on content, not formatting
2. Portability - Plain text files work everywhere
3. Version Control - Track changes with Git
4. Conversion - Export to PDF, DOCX, or LaTeX

These principles align with effective Content Organization and can integrate with a Personal Knowledge Base workflow.

This guide documents all SEO implementations, files, and configurations added to the PKB Hugo theme to ensure optimal search engine visibility and performance.

Theme Integration Architecture

Hugo Theme SEO Architecture
═══════════════════════════════════════════════════════════════════

                     ┌─────────────────┐
                     │   hugo.toml     │
                     │ (Site Config)   │
                     └─────────┬───────┘
                               │
                ┌──────────────┼──────────────┐
                │              │              │
        ┌───────▼──────┐  ┌────▼────┐  ┌─────▼─────┐
        │ data/seo.yml │  │ Content │  │ Static    │
        │ (SEO Config) │  │ Files   │  │ Assets    │
        └───────┬──────┘  └────┬────┘  └─────┬─────┘
                │              │              │
                └──────────────┼──────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   LAYOUT SYSTEM     │
                    │ ─────────────────── │
                    │ baseof.html         │
                    │ ├─ <head>           │
                    │ │  ├─ head/meta     │
                    │ │  ├─ schema-org    │
                    │ │  └─ preload       │
                    │ └─ <body>           │
                    │    └─ content       │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   GENERATED HTML    │
                    │ ─────────────────── │
                    │ • Meta Tags         │
                    │ • Schema Markup     │
                    │ • Preloaded Assets  │
                    │ • Optimized Images  │
                    │ • Robots.txt        │
                    │ • Sitemap.xml       │
                    └─────────────────────┘

Build Process:
Hugo native [sitemap] config ──► sitemap.xml
scripts/optimize-images.js  ──► WebP + responsive images
static/robots.txt ──► Crawler directives

SEO Files Created

Core Requirements (Always Needed)

• /layouts/partials/head/meta.html - Meta tags
• /layouts/partials/seo/schema-org.html - Structured data
• /layouts/partials/seo/preload-resources.html - Performance
• /static/robots.txt - Crawler directives
• /config/_default/params.toml - SEO configuration

Optional Automation (Node.js Required)

• /package.json - Only needed for advanced scripts
• /scripts/optimize-images.js - Image optimization
• /scripts/seo-audit.js - SEO validation

Basic vs Advanced Setup

Basic Setup (Hugo Only)

# No Node.js required
hugo --gc --minify

Features:

This guide covers how to deploy your Hugo site on various hosting platforms, from static site hosts to cloud providers.

Prerequisites

• Hugo site ready for deployment
• Git repository (GitHub, GitLab, etc.)
• Basic command line knowledge

Quick Comparison

Netlify (Recommended)

Best for: Beginners, continuous deployment, form handling

Setting Up Saleor with PKB-theme

This guide provides detailed instructions for developers to install, configure, and integrate Saleor - a modern, GraphQL-first headless commerce platform - with your PKB-theme knowledge base or blog.

Introduction to Saleor

Saleor is a headless e-commerce platform built with Python, Django, and GraphQL. Unlike traditional e-commerce systems, Saleor separates the backend (data and business logic) from the frontend (user interface), allowing for more flexible and customizable implementations.

Setting Up PrestaShop with PKB-theme

This guide walks you through the process of installing, configuring, and integrating PrestaShop with your PKB-theme knowledge base or blog site.

Prerequisites

Before beginning the installation, ensure your environment meets these requirements:

• Web server (Apache, Nginx) with PHP 7.4+ (PHP 8.0+ recommended)
• MySQL 5.6+ or MariaDB 10.0+
• PHP extensions: GD, cURL, SimpleXML, DOM, Zip, PDO, and Mcrypt
• At least 250MB of disk space
• Server memory limit of at least 256MB
• FTP or SSH access to your server
• Database credentials

Installation Process

Step 1: Server Preparation

1. Create a dedicated subdomain (recommended) or subdirectory for your store:

Setting Up OpenCart with PKB-theme

This guide provides comprehensive instructions for installing, configuring, and integrating OpenCart with your knowledge base or blog built with PKB-theme.

Prerequisites

Before beginning the installation, ensure you have:

• Web server with PHP 7.3+ and MySQL 5.6+
• cURL and ZIP PHP extensions enabled
• At least 100MB of disk space
• FTP or SSH access to your server
• Database credentials
• Ability to create subdomains or subdirectories

Installation Process

Step 1: Prepare Your Server Environment

1. Create a dedicated subdomain (recommended) or subdirectory for your store:

Self-Hosted Ecommerce Solutions

This guide introduces privacy-respecting, self-hosted alternatives to commercial ecommerce platforms. These Free and Open Source Software (FOSS) solutions give you complete control over your online store without vendor lock-in or excessive fees.

Why Choose Self-Hosted Ecommerce?

Self-hosting your ecommerce platform offers several advantages:

• Complete Ownership: Full control over your store’s data, appearance, and functionality
• Privacy Focused: No third-party tracking or data collection unless you choose to add it
• No Revenue Sharing: Avoid platform fees that take a percentage of each sale
• Unlimited Customization: Modify any aspect of your store’s code to match your exact requirements
• Scalability Options: Scale your infrastructure as your business grows
• Integration Freedom: Connect with any payment processor, shipping provider, or third-party service
• Community Support: Access large communities of developers and store owners

Ecommerce Solutions Comparison

Detailed Solution Overviews

WooCommerce

WooCommerce is the most popular ecommerce platform, powering over 29% of all online stores.

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:

Reverse Proxy Setup for Self-Hosted Analytics

This guide explains how to properly configure reverse proxies for your self-hosted analytics solutions. A reverse proxy sits between users and your analytics server, providing benefits like SSL termination, load balancing, and additional security.

Comparison of Reverse Proxy Solutions

General Setup Principles

When setting up a reverse proxy for analytics, consider these key principles:

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

Occaecat aliqua consequat laborum ut ex aute aliqua culpa quis irure esse magna dolore quis. Proident fugiat labore eu laboris officia Lorem enim. Ipsum occaecat cillum ut tempor id sint aliqua incididunt nisi incididunt reprehenderit. Voluptate ad minim sint est aute aliquip esse occaecat tempor officia qui sunt. Aute ex ipsum id ut in est velit est laborum incididunt. Aliqua qui id do esse sunt eiusmod id deserunt eu nostrud aute sit ipsum. Deserunt esse cillum Lorem non magna adipisicing mollit amet consequat.