docs 15 ITEMS

Documentation

Architecture, configuration, deployment guides, and component references for the Hugo Carbon theme.

The Hugo Carbon Theme is an open-source, modular static website theme implementing the IBM Carbon Design System v11. It combines Carbon’s 16-column 2x Grid, token-based theming, and accessible interface patterns with the speed and simplicity of Hugo.

Everything runs from origin: IBM Plex fonts, KaTeX mathematics, MapLibre GL vector cartography, and Web Worker data engines are self-hosted with zero external CDNs and zero tracking.

Quick Start

1. Requirements

Install Hugo Extended (version 0.149.0 or higher) to enable Dart Sass and ESBuild:

1
2
3
4
5
# macOS (Homebrew)
brew install hugo

# Linux (Snap or package manager)
snap install hugo --channel=extended

2. Clone & Launch

Clone the repository and start the development server:

1
2
3
git clone https://github.com/caldeira-cc/hugo-theme-carbon.git
cd hugo-theme-carbon/exampleSite
hugo server -p 1316

Open http://localhost:1316/ in your browser. Live reload is active by default.

Documentation Sections

FOUNDATIONS

Architecture & 2x Grid

Fluid 16-column grid system, 8px mini-unit spatial cadence, 4px baseline rhythm, and layout mechanics.

SETUP

Configuration & Cascade

Parameter dictionaries for hugo.yaml, navigation trees, sidebar data, and front-matter cascade rules.

HOSTING

Deployment & Hosting

Step-by-step blueprints for deploying to Cloudflare Pages, GitHub Pages with Actions, Netlify, and static servers.

THEMING

Theme Customisation

Dual-style Light and Dark themes, 18 colour palettes, CSS custom properties, and subdomain token overrides.

SHORTCODES

75+ Shortcodes Catalog

Modular shortcode library grouped into dedicated pages for cards, navigation, typography, forms, and alerts.

DATA SUITE

W3C CSVW Data Engine

Client-side Web Worker table engine with schema metadata, custom status tags, search, and sorting.

CARTOGRAPHY

MapLibre GL Vector Maps

GPU-accelerated vector cartography rendering standard RFC 7946 GeoJSON layers in flat and globe projections.

SECURITY

Client-Side Encryption

Build-time document encryption using PBKDF2 key derivation and Web Crypto AES-256-GCM static decryption.

AI Disclosure & Editorial Transparency

In accordance with official IBM Carbon Design System v11 AI component patterns, all synthetic placeholder text generated with artificial intelligence is marked with the Carbon AI modifier (cds--ai-label):

AI-generated content

This theme documentation strictly distinguishes human-written technical prose from synthetic placeholder text. Wherever machine-assisted content appears, this badge provides direct explainability.

Users can click the AI badge at any time to open an explainability popover detailing how the content was produced.

Architecture