# Geekdoc: a fast and lean Hugo theme for documentation sites > Geekdoc is a Hugo theme for documentation that makes its trade-off explicit in the first paragraph: it is intentionally fast and lean and may not fit complex projects, and if you need a feature-complete theme there are alternatives. What it ships instead is a CI built asset pipeline, an SVG sprite and icon font step, search, maths rendering and localisation, all in a release tarball you can drop into a themes directory. **thegeeklab/hugo-geekdoc** — Hugo theme made for documentation - Repository: https://github.com/thegeeklab/hugo-geekdoc - Website: https://geekdocs.de - Stars: 547 · Forks: 320 - Language: HTML - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/thegeeklab-hugo-geekdoc ## The trade-off stated in the first paragraph Geekdoc is a simple Hugo theme for documentations, and the README does the unusual thing of being honest about the limits immediately. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of great alternatives out there. That paragraph tells you what you are buying. A documentation theme is a decision about how much machinery sits between your Markdown and the browser, and most themes add it: a search index, a theme switcher, a version picker, an editing link, a comment widget, analytics hooks, a set of shortcodes. Geekdoc's position is that a small set of those, done well and built once, beats a large set that you have to configure and maintain. The demo and the full documentation are at geekdocs.de, and the README shows a desktop and mobile preview of the theme. The technical facts are straightforward. The primary language of the repository is HTML, the licence is MIT, the default branch is main, and the Hugo version badge says 0.160. The repository carries a CI build status badge pointing at a Woodpecker instance at ci.thegeeklab.de, a GitHub release badge and a contributors badge. The recent releases are v4.1.2 in August 2026, v4.1.3 in September and v4.1.4 on 2026-10-05, with the last push to the repository on 2026-10-19. The theme is inspired and partially based on the hugo-book theme, and the README thanks Alex Shpak for that work, which is the origin of the book-like layout. ## You cannot use the main branch without building it The build and release section explains a constraint that catches people out, and it is the single most important operational fact about the project. The theme is subject to a CI driven build and release process common for software development. During the release build, all necessary assets are automatically built by webpack and bundled in a release tarball, which you can download from the GitHub release page. And then: due to the fact that webpack and npm scripts are used as pre-processors, the theme cannot be used from the main branch by default. If you want to use the theme from a cloned branch instead of a release tarball, you will need to install webpack locally and run the build script once to create all required assets. The commands for that are short: ```bash # install required packages from package.json npm install # run the build script to build required assets npm run build # build release tarball npm run pack ``` The third command is only for producing your own tarball, and the first two are what a contributor or a person who wants to work from a clone needs. This is a common shape for a modern Hugo theme, and it is worth understanding why. Hugo itself can process SCSS and can bundle assets without a JavaScript toolchain, so a theme could avoid webpack entirely. The reason to use it here is the icon pipeline, which generates an SVG sprite and an icon font from the SVG sources in src/icons. That is a JavaScript build step, and once one exists, the whole asset pipeline goes through npm, and the release artefact has to be produced by the same chain that CI runs. The consequence for users is simple: use the release tarball and you are done. The Getting Started Guide covers the different setup options. ## What the npm scripts actually do The package.json scripts are the clearest description of the build, and they are worth reading as a pipeline diagram. The build script is a sequence: prep:clean, then prep:make, then svg, then build:webpack, with build:webpack running webpack in production mode and a separate build:webpack-devel for development. The pack script produces the release artefact, a tarball written with tar and the .tarignore file controlling what is included. The start script is the development equivalent, and it does something a little unusual: it runs the preparation and the development webpack build, then runs the webpack watcher and the Hugo server in parallel with run-p. The Hugo side is pointed at the example site with hugo server -D -F -s exampleSite/, where the -D flag is the draft content flag and -F is the fast render mode. The preparation steps are small shell operations. prep:clean removes the build and static directories with shx, and prep:clean-all is the nuclear version, taking out the VERSION file, the Lighthouse CI directory and reports, the build, dist and static directories, the data directory, the generated sprites in assets and in the example site, and the example site's public, resources and lock directories. prep:make creates the build icons and fonts directories and the dist directory. The lint script runs the JavaScript lint and the HTML validation in parallel, with eslint over src/js/ and html-validate pointed at the built example site output. So there are three separate cleaning levels and a build that has to run in a specific order, which is the usual shape of a project with generated assets. The generated files are the reason the tree looks untidy, and the clean targets are how the maintainers keep it honest. ## Icons, from SVG sources to a sprite and a font The icon pipeline is the reason this theme needs a JavaScript toolchain at all, and it is a neat piece of engineering. The svg script runs the two svg sub-scripts in sequence. svg:sprite runs svg-sprite with the svgsprite.config.json configuration over the SVG files in src/icons, producing a sprite. svg:font runs svgtofont over the built icons and writes the output into build/fonts. So the same SVG sources produce two things: a sprite for the current colour, and an icon font for the cases where a font is easier to style, colour and size in text. The svgsprite.config.json file at the repository root is the configuration for the sprite step, and the src/ directory holds the icon sources. Then there is svg-sprite-list, which is the step that connects the generated font to the example site: it prepares the directories, runs the svg pipeline, and copies build/fonts/GeekdocIcons.json into exampleSite/data/sprites/geekdoc.json. That JSON file is the metadata the theme reads to know which icon names exist, so the copy is what makes a newly added icon appear rather than being silently unknown. The licence section explains why the icons are a separate topic: the used SVG icons and generated icon fonts are licensed under the licence of the respective icon pack. Font Awesome is under CC BY 4.0, the IcoMoon Free Pack under GPL with CC BY 4.0, and Material Icons under the Apache License 2.0. That middle entry is the one to note. A GPL component inside an otherwise MIT theme is a distribution consideration, and it applies to the generated icon font rather than to the theme's own code. The theme itself remains MIT licensed, and the README says so in its own licence section. ## The repository as a documentation toolchain The top level of the repository is longer than a Hugo theme usually is, and the extra files describe the checks the project runs on itself. The theme parts are the familiar ones: layouts/ for the templates, assets/ for the SCSS and assets, src/ for the JavaScript and the icon sources, i18n/ for the translations, archetypes/ for the content scaffolding, exampleSite/ for the demo site used during development, images/ for the README assets, and theme.toml for the Hugo theme metadata. Then there are the configuration files, and they are the interesting part. eslint.config.js for the JavaScript linting, and .jsbeautifyrc alongside it. .markdownlint.yaml for the Markdown, .htmlvalidate.json for the HTML of the built output, .cspell.json for spelling, .prettierrc and .prettierignore for formatting, and .yamlfmt.yaml for the YAML files. Two of those are unusual enough to call out: .lychee.toml configures a link checker, which is how a documentation site catches the dead external links that documentation accumulates, and .lighthouserc.yaml configures Lighthouse performance checks, which is a sensible thing to run against a theme whose whole claim is speed. There is also .nvmrc pinning the Node version, .npmrc for npm behaviour, renovate.json for dependency updates, .tarignore controlling the release tarball contents, and .woodpecker/ holding the CI configuration for the Woodpecker instance the build badge points at. The .gitsv/ directory holds versioning metadata for the release process. The runtime JavaScript dependencies explain what the lean theme still ships with: flexsearch for the client side search, katex for maths rendering, clipboard for copy to clipboard, lodash, and a JSON schema package. So the theme does include search and maths, and it does include the small conveniences, it just does not include everything. ## Where Geekdoc is the wrong theme There are clear cases where this theme is the wrong answer, and the README names them before you install it. If your documentation project is complex, with many sections, heavy customisation needs and a long feature list of its own, this theme will not fit. The README says so explicitly, and a theme that is deliberately fast and lean has no room for a layout you did not anticipate. In that case the honest advice is to use one of the feature-complete alternatives, and the README's next sentence is the recommendation to do exactly that. There is also the practical friction of the build. A team that wants to contribute a documentation change, or to fork the theme and adjust the design, has to install Node and webpack and run the build before Hugo will render anything. For a team whose documentation changes are made by people who write Markdown and nothing else, that is a barrier. The release tarball avoids it, and the alternative is to write your own minimal theme, which for a very simple documentation site is sometimes less work than adapting somebody else's. The third consideration is the icon licensing, which the README separates from the theme licence. The theme code is MIT, but the icons come from three packs with three sets of terms, and one of them, the IcoMoon Free Pack, is offered under GPL with CC BY 4.0. If you distribute the built site, that is a question about the generated icon font rather than about the theme. The last thing to weigh is the Hugo version. The badge says 0.160, which is a specific version rather than a range, so if you pin your site to an older Hugo the theme may not build, and a theme release every few weeks, v4.1.4 in October 2026, means it moves. ## Conclusion Geekdoc suits a team documenting one product, with a handful of pages and a versioned structure, that values a fast site and a small theme over a long feature list. It does not suit a documentation set with heavy site-wide interactivity, because the theme states that it may not fit the requirements of complex projects, and it does not suit anybody who expects to clone the repository and run Hugo immediately. Check three things before you adopt it: whether you will use a release tarball rather than the main branch, since the theme cannot be used from the main branch by default because webpack and npm scripts are the pre-processors, which Hugo version you need, with the badge stating 0.160, and whether the icon licensing suits you, since the icon packs are under three different terms including one copyleft pack. The last push to the repository was on 2026-10-19 and the newest release is v4.1.4. ## FAQ ### What is Geekdoc? It is a simple Hugo theme for documentation sites, intentionally designed as a fast and lean theme, and the README is explicit that it may not fit the requirements of complex projects and that feature-complete alternatives exist. The demo and full documentation are at geekdocs.de. ### Can I use Geekdoc from the main branch? Not by default. Because webpack and npm scripts are used as pre-processors, the theme cannot be used from the main branch without installing webpack locally and running the build script once to create the required assets. The normal route is to download the release tarball from the GitHub release page. ### How do I build the Geekdoc assets locally? Run npm install to install the packages from package.json, then npm run build to build the required assets, and npm run pack if you want to produce a release tarball. The build sequence is prep:clean, prep:make, svg and build:webpack, with the svg step producing an SVG sprite and an icon font from the sources in src/icons. ### What licence applies to the Geekdoc theme and its icons? The theme itself is MIT licensed. The SVG icons and the generated icon fonts are licensed under the terms of their respective packs: Font Awesome under CC BY 4.0, the IcoMoon Free Pack under GPL with CC BY 4.0, and Material Icons under the Apache License 2.0. ### Which Hugo version does Geekdoc target? The badge in the README states Hugo 0.160. The theme also relies on Node, with the package manifest requiring node >=20 <=24 and an .nvmrc pinning the version used in development. ## Sources - [License: MIT](https://github.com/thegeeklab/hugo-geekdoc/blob/main/LICENSE) - [Project website](https://geekdocs.de) - [README](https://github.com/thegeeklab/hugo-geekdoc/blob/main/README.md) - [Releases](https://github.com/thegeeklab/hugo-geekdoc/releases) - [thegeeklab/hugo-geekdoc on GitHub](https://github.com/thegeeklab/hugo-geekdoc) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/thegeeklab-hugo-geekdoc