# Lotus Docs: a Bootstrap 5 Hugo theme for documentation sites

> Lotus Docs is a MIT licensed Hugo theme for building documentation sites, with a Bootstrap 5 base, dark mode, Prism syntax highlighting, Mermaid diagrams, KaTeX maths, FlexSearch or DocSearch, i18n and a landing page template. It installs as a Hugo module, a Git submodule or a local clone, and the README does not document a single command for building it.

**colinwilson/lotusdocs** — 📖 A free, lightweight, modern documentation theme for Hugo

- Repository: https://github.com/colinwilson/lotusdocs
- Website: https://lotusdocs.dev/docs/
- Stars: 695 · Forks: 137
- Language: JavaScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/colinwilson-lotusdocs

## What Lotus Docs is, and what the docs site doubles as

Lotus Docs is described as a free, lightweight and modern documentation theme for Hugo, and the README calls it an easily updated and customisable Hugo theme for building fast, secure and SEO-friendly documentation sites. The demo site at lotusdocs.dev/docs/ is pointed at as both a demo and the documentation guide for the theme, which is a neat arrangement: the theme documents itself. The author is Colin Wilson, with a copyright notice covering 2022 to 2025, and the repository is MIT licensed. The primary language of the repository is JavaScript, which fits a theme that ships styling, shortcodes and browser side behaviour, and the topic list names Bootstrap 5, Hugo, documentation theme, Jamstack, responsive and Vercel. The default branch is named release, which is a small signal that the published state lives there.

## The feature list, and where the theme adds more than a layout

The feature checklist is long and it is where the theme's value is. The layout is a modern documentation one, responsive with mobile support, and the README claims fast, accessible and SEO-friendly output with four perfect scores on Google Lighthouse, which is the kind of claim you should check for yourself on your own content rather than take on trust. Security by default is on the list, as is a Bootstrap 5 base. Beyond the shell there is real functionality: multilingual support through i18n, syntax highlighting via Prism.js, dark mode, custom fonts through Google Fonts and custom icons through the Google icon set, a landing page template, a documentation sidebar menu with optional icons, an optional table of contents menu on each page, a customisable theme accent colour, social media links, static search powered by FlexSearch and enabled by default, support for DocSearch, custom shortcodes for PrismJS, alerts, tabs and tables, analytics for Google Analytics v4 and Plausible, a feedback widget, math equations through KaTeX, Mermaid support and Open Graph metadata. Cross-browser testing via BrowserStack is also claimed.

## Requirements, and the module bootstrap you cannot skip

The requirements are three lines: Hugo Extended with a minimum version of 0.140.0, git, and Go with a minimum version of v1.21. The Extended edition matters because the theme uses SCSS through the Hugo Bootstrap Module, and the Go requirement matters because Hugo modules are resolved with the Go toolchain. The README is explicit that the theme makes use of the Hugo Bootstrap Module from gohugoio, and that for this reason it is necessary to initialize your site as a Hugo module. If your site is not one already, the command is given.

```bash
hugo mod init github.com/<username>/<your-hugo-site-name>
```

There is a prerequisite worth noting that is easy to skim past: a contentDir present in the project folder. The theme expects content to live under a content directory, and the later example writes pages to content/docs, so the directory layout has to match before the theme will behave as the documentation expects.

## Three install routes, and the config differences between them

Lotus Docs can be installed as a Hugo module, which the README marks as recommended, as a Git submodule, or by cloning the theme files locally. The module route means adding two module imports to hugo.toml, one for the theme and one for the Bootstrap SCSS module, plus the markup settings that allow raw HTML and block attributes in Markdown.

```toml
[module]
    [[module.imports]]
        path = "github.com/colinwilson/lotusdocs"
        disable = false
    [[module.imports]]
        path = "github.com/gohugoio/hugo-mod-bootstrap-scss/v5"
        disable = false

[markup]
    [markup.tableOfContents]
      endLevel = 3
      startLevel = 1
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true # https://jdhao.github.io/2019/12/29/hugo_html_not_shown/
  [markup.goldmark.parser]
    [markup.goldmark.parser.attribute]
      block = true
```

The submodule route clones the theme into themes/lotusdocs and adds a module replacement line pointing github.com/colinwilson/lotusdocs at the local lotusdocs path, which is the same trick the local clone route uses. The README explains that the replacement line is for temporary local development of the module, or when using the theme as a Git submodule, and the local clone route is for people who would rather customise and maintain the theme themselves.

## Writing the first page and seeing it locally

Content creation follows the usual Hugo pattern, with the documentation layout as the target directory. The command creates a file in content/docs.

```bash
hugo new docs/example-page.md
```

The generated front matter shows what the theme expects on every page, and the fields are the theme's own vocabulary rather than Hugo's defaults.

```yaml
---
title: "Example Page"
description: ""
icon: "article"
date: "2023-05-22T00:27:57+01:00"
lastmod: "2023-05-22T00:27:57+01:00"
draft: false
toc: true
weight: 999
---
```

The icon field ties into the icon set the theme uses and the optional sidebar icons, toc controls the per-page table of contents that the feature list marks as optional, and weight sets the ordering. The preview step is a Hugo server run in draft mode, after which you open localhost:1313/docs/ and should see a card link to the example page. The README does not document a build command for the site itself, which is a gap you will notice if you are deploying with a static build pipeline.

## Deployment, the repository layout, and what is not there

Deployment options are listed in the feature checklist rather than in a deployment section, and they cover GitHub Pages, GitLab Pages, Vercel, Netlify and Cloudflare Pages, with the documentation linking to a deployment page for each of the first two. The repository tree is a standard Hugo theme: layouts/, assets/, static/, images/, i18n/, data/, archetypes/ for the content scaffolding, an exampleSite/ for the demo content, a theme.toml, a netlify.toml, a config.toml and a SECURITY.md, alongside a go.mod that declares the module as github.com/colinwilson/lotusdocs with go 1.21. What is absent matters as much. There is no exampleSite configuration in the README showing a full production hugo.toml, no documented build command for CI, and no explanation of how the FlexSearch index is generated or where the DocSearch crawler configuration lives, even though search is enabled by default. The theme also assumes the Bootstrap SCSS module is present, so a fork that drops that dependency inherits a broken stylesheet pipeline.

## The limits, and how it compares to the built-in Hugo alternative

The first limit is the floor. Hugo Extended 0.140.0, Go 1.21 and git are prerequisites, and the Go requirement in particular puts a toolchain on the machine of anyone who only wants to read the docs site locally. The second is that the scope is a documentation site, not a marketing site or a blog, and the theme's own structure reinforces that with the content/docs path, the sidebar model and the landing page template bolted on top. The comparison worth making is with other Hugo documentation themes in general: Lotus Docs buys you a finished Bootstrap 5 visual identity, dark mode, the landing page, the feedback widget and the analytics and search integration, at the cost of a theme that pulls in a second module (the Hugo Bootstrap Module) and expects a specific hugo.toml shape. The maintenance record is the other thing to weigh. The repository is not archived and the last push was on 2026-06-02, with releases v0.3.0 from 2026-04-17, v0.2.0 from 2025-01-28 and v0.1.0 from 2023-10-01, so the line is young and the version numbers are still low.

## Conclusion

Adopt Lotus Docs if you are building a documentation site with Hugo and want a finished, accessible, search-enabled theme with a landing page and a documentation layout already solved. Do not adopt it if your documentation lives elsewhere, since this is a Hugo theme and the whole installation path depends on Hugo Extended and Go being present. Before you start, note the floors the README sets, Hugo Extended 0.140.0 or newer, Go 1.21 or newer, and git, and confirm the module import path you use, because the recommended install and the submodule install need slightly different module configuration.

## FAQ

### What is Lotus Docs?

It is a free, lightweight and modern documentation theme for Hugo, described as easily updated and customisable, for building fast, secure and SEO-friendly documentation sites. The demo site at lotusdocs.dev/docs/ doubles as the theme's own documentation guide.

### What does Lotus Docs require before I can use it?

The README lists Hugo Extended with a minimum version of 0.140.0, git, and Go with a minimum version of v1.21. A contentDir must also be present in the project folder, and the site has to be initialized as a Hugo module because the theme uses the Hugo Bootstrap Module.

### How do I install the Lotus Docs theme?

There are three routes: as a Hugo module, which the README marks as recommended, as a Git submodule with git submodule add https://github.com/colinwilson/lotusdocs themes/lotusdocs, or by cloning the theme files into themes/lotusdocs. Each route needs a slightly different module configuration in hugo.toml.

### What search does Lotus Docs use?

The README lists a static search plugin option powered by FlexSearch that is enabled by default, and also support for DocSearch. It does not document how the FlexSearch index is generated, which is worth checking before relying on it.

### Where can a Lotus Docs site be deployed?

The feature list names GitHub Pages, GitLab Pages, Vercel, Netlify and Cloudflare Pages, and the documentation links a deployment page for GitHub Pages and GitLab Pages. The repository also carries a netlify.toml, and the topic list includes vercel.

## Sources

- [colinwilson/lotusdocs on GitHub](https://github.com/colinwilson/lotusdocs)
- [License: MIT](https://github.com/colinwilson/lotusdocs/blob/release/LICENSE)
- [Project website](https://lotusdocs.dev/docs/)
- [README](https://github.com/colinwilson/lotusdocs/blob/release/README.md)
- [Releases](https://github.com/colinwilson/lotusdocs/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/colinwilson-lotusdocs