This is the supplementary theme meant for the CMS-PKB-Blogger project. This template is meant for a blog oriented towards a Personal Knowledge Management (PKB). The theme is inspired in some subjects of Edward Tufte's work, the PKB, and Gwerns' blog design.
If you already have a populated HUGO site, make sure that this installation steps adjust to you context; check the installation and customization flowchart. For any other doubt, read the FAQ.
Have HUGO and Git installed in your system.
From your project's root directory, initiate the hugo module system and add the theme's repo to your config.toml. A module is a collection of related Go packages that are versioned together as a single unit.
# 0. Create boilerplate files for your site, replace placeholder title (in case of testing locally anything like <example.com/my-blog> works fine)
hogo new site <your-site>
# 1. Initialize HUGO module to go.mod
hugo mod init github.com/stradichenko/PKB-theme
# 2. Create config.toml with module config
cat <<EOF >> config.toml
[module]
[[module.imports]]
path = 'github.com/stradichenko/PKB-theme'
EOF
# 3. Download the theme
hugo mod get github.com/stradichenko/PKB-theme
# 4. This will use HUGO to Auto-create archetype for the user to customize
curl -L -o archetypes/default.md https://github.com/stradichenko/PKB-theme/raw/main/archetypes/default.md
The easiest way to keep the module updated while allowing you to populate the theme with your preferences is to copy the archetype (or any other personalized files) from the theme into their site’s own archetypes/ directory. Since Hugo gives precedence to local files over module files, any customizations (such as personal profile information) remain in place even if the theme updates. Since Hugo gives precedence to local files over module files, any customizations (such as personal profile information) remain in place even if the theme updates.
hugo new site <YOURWEBSITENAME>
cd <YOURWEBSITENAME>
git init
git submodule add https://github.com/stradichenko/PKB-theme.git themes/PKB-theme
echo "theme = 'PKB-theme'" >> hugo.tomlInside your folder you can always use the command hugo server and check it with localhost:1313 in the address bar of your browser. The hugo server command starts a local development server that watches for changes in your files and automatically regenerates the site and refreshes the browser. This is useful for live previewing changes as you develop your site. Press CTRL + <C> to stop Hugo’s development server.
Described at documentation, these are the initial steps to understand how you can customize your blog to your liking.
By default, running the command hugo will generate the static files for your website from your content and templates. The generated files will be placed in the public directory (or another specified output directory).
You can start by:
hugo new site <your-site-name>
cd <your-site-name>Tipically the options would be to create a new theme with the command hugo new theme <THEMENAME>. Or, install a theme from https://themes.gohugo.io/. But in this case the installation will come from the instructions above this repo.
When you install a theme as a Hugo module, Hugo manages the theme as a dependency rather than copying its files directly into your project's themes/ folder. You’re telling Hugo to treat your project as a module. In practical terms, this command creates a go.mod file in your project’s root directory. This file is a key component of Go’s module system and serves as a manifest that lets Hugo manage dependencies (like themes or other modules) and control versioning. Without running this initialization, Hugo wouldn’t know to look for or handle module-based imports in your project.
- Module Cache: Hugo Modules are managed through Go's module system, which downloads and stores the theme in an internal module cache. The files remain there and are referenced during the build process.
- Separation of Dependencies: Unlike Git submodules, which add a physical copy of the theme into your repository (typically under themes/), Hugo Modules keep the dependency separate. This helps with cleaner project management and easier updates.
- On-Demand Access: The theme files are automatically fetched and used when you build your site. You don’t need a local copy in your themes/ folder for Hugo to incorporate them.
When you run hugo mod init,
| Method | Pros | Cons |
|---|---|---|
| Hugo Module | Easier dependency management, automatic updates, no need to track theme files in your project. | Requires Hugo Modules (Go-based). |
| Git Submodule | Works well with Git workflows, allows manual control of theme updates. | More manual updates, extra Git commands needed. |
If you’re using Hugo Modules, you can just run:
hugo mod get -u github.com/stradichenko/PKB-theme
cat go.mod | grep "github.com/stradichenko/PKB-theme"to update the theme. If you ever need to see a local copy of all module files, you can use the command hugo mod vendor.
which will copy all module dependencies into a vendor/ folder.
If you’re using Git submodules, you need to run:
git submodule update --remote --mergeto fetch the latest theme updates.