Lily Docs

Low maintenance Hugo theme for building fast, secure, and SEO-friendly documentation sites.

Documentation

Lily Docs is built on Bootstrap 5 and offers a range of powerful features out of the box, including syntax highlighting via Prism.js, dark mode, custom fonts and icons, static search, analytics, math equations via KaTeX, Mermaid diagram support, and more. The theme is highly customizable, allowing you to tailor the accent color, navigation, and other aspects to your needs.

Whether you're building documentation for an open source project, internal knowledge base, or product manual, Lily Docs makes it easy to create professional-looking documentation sites that are fast, accessible, secure, and optimized for search engines. Deploy it easily on popular static hosting platforms like GitHub Pages, GitLab Pages, Vercel, Netlify, or Cloudflare Pages.

Features

• Modern documentation layout
• Responsive design / Mobile support
• Fast, Accessible and SEO-Friendly (4 x 💯 scores on Google Lighthouse!)
• Secure by default
• Built on Bootstrap 5
• Deploy on GitHub Pages, GitLab Pages, Vercel, Netlify, or Cloudflare Pages
• Multilingual support (i18n)
• Powerful Syntax Highlighting via Prism.js
• Dark Mode
• Custom fonts (via Google Fonts)
• Custom icons (via Google Material Symbols)
• Landing page template included
• Documentation sidebar menu (with optional icons)
• Table of Contents menu on each page (optional)
• Customisable theme accent colour
• Social media links (Github, Twitter, Instagram etc)
• Static Search plugin option (powered by FlexSearch, enabled by default)
• Support for DocSearch
• Custom shortcodes (PrismJS, Alerts, Tabs, Tables)
• Analytics (Google Analytics v4, Plausible Analytics)
• Cross-browser testing via BrowserStack
• Feedback widget
• Math equations powered by KaTeX
• Mermaid Support
• Open Graph

Requirements

• Hugo Extended (>=v0.120.0)
• Go (>=v1.20)
• git

Installation

The Lily Docs theme can be installed using one of the following methods. You must first have a Hugo site; for example, we create a new site called quick site.

hugo new site quicksite
cd quicksite

An initialized git repository is also necessary.

git init

Install as a Git Submodule

If you prefer to install the Lily Docs theme as a Git submodule, follow these steps:

1. Open your terminal and navigate to the root directory of your Hugo project.

2. Add the Lily Docs theme as a Git submodule by running the following command:

git submodule add https://gitlab.com/oasci/lilydocs themes/lilydocs

This command will create a themes directory (if it doesn't already exist) and clone the Lily Docs theme repository into the themes/lilydocs directory.

3. Open the hugo.toml configuration file in your project's root directory and add the following lines:

baseURL = 'http://example.org/'  # Change this to your site's url
languageCode = 'en-us'
title = 'My New Hugo Site'  # Change this to your site's name

[module]
    # uncomment line below for temporary local development of module
    # or when using a 'theme' as a git submodule
    replacements = "gitlab.com/oasci/lilydocs -> lilydocs"
    [[module.imports]]
        path = "gitlab.com/oasci/lilydocs"
        disable = false
    [[module.imports]]
        path = "github.com/gohugoio/hugo-mod-bootstrap-scss/v5"
        disable = false

The replacements line tells Hugo to use the submodule located in the themes/lilydocs directory instead of fetching it from the remote repository.

4. Save the changes to the hugo.toml file.

Remember to commit the changes to your project's repository after adding the submodule:

git add .
git commit -m "Add Lily Docs theme as a submodule"

Locally

There may be cases where you prefer to customize and maintain the Lily Docs theme yourself. In such cases, use git to clone the theme into the themes/lilydocs directory.

git clone https://gitlab.com/oasci/lilydocs themes/lilydocs

Edit the hugo.toml config file:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

[module]
    # uncomment line below for temporary local development of module,
    # when using a 'theme' as a git submodule or git cloned files
    replacements = "gitlab.com/oasci/lilydocs -> lilydocs"
    [[module.imports]]
        path = "gitlab.com/oasci/lilydocs"
        disable = false
    [[module.imports]]
        path = "github.com/gohugoio/hugo-mod-bootstrap-scss/v5"
        disable = false

Create New Content

Navigate to the root of your Hugo project and use the hugo new command to create a file in the content/docs directory:

hugo new docs/example-page.md

This will create a markdown file named example-page.md with the following default front matter:

---
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
---

Modify the above front matter options to suit your needs.

Preview your site locally

Now that you've created some sample content you can preview your new Lily Docs site using the huge server command:

hugo server -D

Navigate to http://localhost:1313/docs/ and you should see a card link to the Example Page created earlier.

If you are making changes to the theme, you can use

hugo server --disableFastRender

to have hugo do a full rebuild upon changes.