Capsule is a CSS-only Hugo theme that builds static sites on the Bulma CSS framework and Font-Awesome icons, with no JavaScript needed for the core layout.
What is Capsule?
Capsule is a Hugo theme that renders a static website from markdown content using the Bulma CSS framework for styling and Font-Awesome for icons. It takes a standard Hugo content directory as input and outputs a responsive, CSS-only site; the theme is installed via Git submodule and is maintained by the GitHub user sudorook. Its core function is to provide a clean, fast layout without requiring front-end build steps for JavaScript, making it a lightweight option for Hugo users.
Key Features
- CSS-only design — The layout uses only Bulma CSS classes, so no JavaScript is required for the core functionality, keeping page weight low.
- Pygments syntax highlighting — Code blocks use Hugo's built-in pygments support; set
pygmentsstylein config.toml to choose the highlighter theme. - Bulma class compilation — Capsule compiles only the Bulma classes it needs; uncomment SASS files in build/bulma/bulma.sass to enable additional Bulma components.
- Automatic navbar menu — Setting
SectionPagesMenu = "main"in config.toml makes the navbar generate a menu from all sections in the content/ directory. - Git metadata notes — With
enableGitInfo = trueand arepoparameter, each page shows a "Last edited on" note with the last commit date and a link to the blob on a public git repository (GitHub, GitLab, or similar). - Per-page custom CSS/JS — Add
cssorjsfields in TOML front matter to inject custom styles or scripts into the page head. - Table of contents — Setting
toc = truein a page's front matter generates a TOC from all headers in the markdown, with nesting matching header levels. - Customizable build — The Sass source in build/sass can be edited and recompiled with
npm run build, allowing complete styling changes.
Who is it for?
- Hugo users who want a minimal, CSS-only theme without JavaScript; they can add Capsule as a submodule and start writing markdown.
- Technical writers building documentation sites find the built-in TOC, syntax highlighting, and automatic section-based navbar useful.
- Theme developers who want to customize Sass can fork the repo or symlink a custom build into Hugo's themes directory.
What can you do with Capsule?
- Bloggers — Create a code-rich blog with pygments-highlighted snippets and a per-page TOC; the git "Last edited" note keeps readers informed of content freshness.
- Documentation authors — Organize a manual into sections and use the auto-generated navbar plus per-page TOCs for easy navigation.
- Personal or portfolio sites — Use Bulma's responsive grid and Font-Awesome icons to showcase projects without a separate build step.
FAQ
How do I install Capsule?
From the base of your Hugo site, run git submodule add https://github.com/sudorook/capsule themes/capsule, then either build with -t capsule or set theme = "capsule" in config.toml.
How do I enable dark syntax highlighting?
Set pygmentsstyle = "<style>" in config.toml and rebuild Capsule's CSS with the syntax.sass file uncommented, then run npm run build. Without that, the background stays light and dark-theme colors are hard to read.
Can I add custom JavaScript to a page?
Yes, put a js field in the page's TOML front matter with the script content; Capsule injects it into the site head when rendering that page.
How do I generate a table of contents?
Add toc = true to the page's TOML front matter. The TOC will include all headers defined in the markdown, with nesting levels matching header weights.
Does Capsule support Git metadata?
Yes, set enableGitInfo = true and provide a repo URL in config.toml. Capsule then displays the last commit date and a link to the blob on your public repository, compatible with GitHub, GitLab, and others.
