Vortisil is a fast, minimal, and restrained Hugo theme for blogs, created by khitezza, that turns Markdown content into a responsive static site with dark/light themes, full-text search, and optional math rendering.
What is Vortisil?
Vortisil is a Hugo theme (not a standalone site builder) designed for personal blogs and content sites. It takes Markdown-based content managed through Hugo's content/ directory and produces a static website with a blog layout, homepage works showcase, archives, and search. The theme is distributed as a public GitHub repository and requires Hugo Extended version 0.116.0 or higher. It is written by khitezza and released under the GNU General Public License v3.0.
Key Features
- Light/Dark theme — Toggleable via CSS variables; both themes are defined in
assets/assets/scss/custom.scssand the primary color can be overridden per theme. - All-article search — Client-side search over all posts, activated through the search menu item.
- MathJax rendering — Set
math = truein a post's front matter or site config to render LaTeX formulas; the theme loads MathJax.js. - Giscus comments — Integrated with Giscus, a GitHub Discussions-based comment system; configure
repo,repoId,category,categoryId, andmappinginhugo.toml. - Responsive design — Layout adapts to mobile and desktop viewports.
- Works showcase — The homepage displays a works/projects list defined in
data/works.toml. - Localization via
data/l10n.toml— Translation strings for home, about, archives, search, and other UI text are stored in this file; contributors can submit translations via git patch or pull request. - Deployment-ready GitHub Actions workflow — A sample
.github/workflows/gh-pages.yamlbuilds the site with Hugo and deploys to GitHub Pages, including Dart Sass installation and caching.
Who is it for?
- Technical bloggers — Write Markdown posts with optional math formulas (MathJax) and publish to GitHub Pages with the provided CI workflow.
- Minimalist writers — The theme's restrained design avoids clutter and focuses on reading, with pagination and archives.
- Developers who want Giscus comments — Easily add GitHub-backed comments by filling in a few settings in
hugo.toml. - Self-hosters and open-source enthusiasts — The theme is free (GPL v3.0) and can be customized via SCSS overrides.
What can you do with Vortisil?
- Create a math-heavy blog: Set
math = truein front matter and write LaTeX formulas that render via MathJax. - Publish a personal portfolio with a works section: Define projects in
data/works.tomland they appear on the homepage. - Deploy a static blog to GitHub Pages: Use the included GitHub Actions workflow and add a
CNAMEfile for custom domains. - Localize the UI: Edit
data/l10n.tomlto translate the theme's strings, or contribute a translation.
How does Vortisil work?
The theme is added to a Hugo site as a git submodule (git submodule add https://github.com/khitezza/vortisil themes/vortisil). Content is created with hugo new content posts/YYYY-MM-DD-Title.md, and site-wide settings live in hugo.toml (theme, params, menus, markup highlighting style). Customization is done by editing SCSS variables, providing logo/favicon images in specific asset paths, and optionally enabling comments and math. Deploying to GitHub Pages is automated with the provided workflow.
FAQ
Is Vortisil free?
Yes. Vortisil is open source and licensed under the GNU General Public License v3.0.
How do I enable mathematical formulas?
Set math = true in your hugo.toml [params] or per-post in front matter. The theme then loads MathJax.js to render LaTeX.
Does Vortisil support multiple languages?
It supports localization through a data/l10n.toml file rather than a full i18n system; translations are community-contributed via git patches or pull requests.
How do I deploy Vortisil to GitHub Pages?
Copy the provided .github/workflows/gh-pages.yaml into your repository, set your baseURL or add a CNAME, and push to the trunk branch. The workflow builds with Hugo Extended and deploys.
What are the system requirements?
You need Hugo Extended (version 0.116.0 or higher), Git, and optionally Dart Sass when running the provided GitHub Actions build.
