Add Lotusdocs theme
This commit is contained in:
Abner Coimbre
207
themes/lotusdocs/README.md
Normal file
207
themes/lotusdocs/README.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Lotus Docs
|
||||
|
||||
[Lotus Docs](https://lotusdocs.dev) is an easily updated and customisable [Hugo](https://gohugo.io/) theme for building fast, secure, and SEO-friendly documentation sites.
|
||||
|
||||
|
||||
|
||||
Check out the demo site [https://lotusdocs.dev/docs/](https://lotusdocs.dev/docs/) (also doubles as the documentation guide for Lotus Docs 📖)
|
||||
|
||||
## Features
|
||||
|
||||
* [x] Modern documentation layout
|
||||
* [x] Responsive design / Mobile support
|
||||
* [x] Fast, Accessible and SEO-Friendly (4 x 💯 scores on [Google Lighthouse](https://pagespeed.web.dev/)!)
|
||||
* [x] Secure by default
|
||||
* [x] Built on Bootstrap 5
|
||||
* [x] Deploy on [GitHub Pages](https://lotusdocs.dev/docs/deployment/platforms/github-pages/), [GitLab Pages](https://lotusdocs.dev/docs/deployment/platforms/gitlab-pages/), [Vercel](https://vercel.com/), [Netlify](https://netlify.com), or [Cloudflare Pages](https://pages.cloudflare.com/)
|
||||
* [x] Multilingual support (i18n)
|
||||
* [x] Powerful Syntax Highlighting via [Prism.js](https://prismjs.com/)
|
||||
* [x] Dark Mode
|
||||
* [x] Custom fonts (via [Google Fonts](https://fonts.google.com/))
|
||||
* [x] Custom icons (via [Google Material Symbols](https://fonts.google.com/icons?icon.style=Outlined&icon.set=Material+Symbols))
|
||||
* [x] Landing page template included
|
||||
* [x] Documentation sidebar menu (with optional icons)
|
||||
* [x] Table of Contents menu on each page (optional)
|
||||
* [x] Customisable theme accent colour
|
||||
* [x] Social media links (Github, Twitter, Instagram etc)
|
||||
* [x] Static Search plugin option (powered by [FlexSearch](https://github.com/nextapps-de/flexsearch), enabled by default)
|
||||
* [x] Support for [DocSearch](https://docsearch.algolia.com/)
|
||||
* [x] Custom shortcodes (PrismJS, Alerts, Tabs, Tables)
|
||||
* [x] Analytics ([Google Analytics v4](https://analytics.google.com/analytics/web/), [Plausible Analytics](https://plausible.io/))
|
||||
* [x] Cross-browser testing via [BrowserStack](https://browserstack.com)
|
||||
* [x] Feedback widget
|
||||
* [x] Math equations powered by [KaTeX](https://katex.org/)
|
||||
* [x] [Mermaid](https://mermaid.js.org/) Support
|
||||
* [x] [Open Graph](https://ogp.me/)
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Requirements
|
||||
|
||||
- Hugo **Extended** (minimum version: 0.140.0)
|
||||
- git
|
||||
- Go (minimum version v1.21)
|
||||
|
||||
### Initialize your site as a Hugo Module
|
||||
|
||||
The Lotus Docs theme makes use of the [Hugo Bootstrap Module](https://github.com/gohugoio/hugo-mod-bootstrap-scss). For this reason, it's necessary to initialize your site as a Hugo Module. If your site isn't already, use the `hugo mod init` command to initialize your site as a Hugo module:
|
||||
|
||||
```bash
|
||||
hugo mod init github.com/<username>/<your-hugo-site-name>
|
||||
```
|
||||
|
||||
### Install Options
|
||||
|
||||
The Lotus Docs theme can be installed using one of the following methods:
|
||||
|
||||
- As a Hugo Module[^1] (recommended)
|
||||
- As a Git submodule
|
||||
- Clone the theme files locally
|
||||
|
||||
Prerequisites:
|
||||
- `contentDir` present in project folder
|
||||
|
||||
### Install as a Hugo Module (recommended)
|
||||
|
||||
Edit the `hugo.toml` configuration file to include the [Lotus Docs theme](https://github.com/colinwilson/lotusdocs) and the [Hugo Bootstrap module](https://github.com/gohugoio/hugo-mod-bootstrap-scss) as modules:
|
||||
|
||||
```toml
|
||||
baseURL = 'http://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'My New Hugo Site'
|
||||
contentDir = 'content'
|
||||
enableEmoji = true
|
||||
|
||||
[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
|
||||
```
|
||||
|
||||
### Install as a Git Submodule
|
||||
|
||||
From the root of your project run the following `git` commands:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git submodule add https://github.com/colinwilson/lotusdocs themes/lotusdocs
|
||||
```
|
||||
|
||||
Edit the `hugo.toml` config file:
|
||||
|
||||
```toml
|
||||
baseURL = 'http://example.org/'
|
||||
languageCode = 'en-us'
|
||||
title = 'My New Hugo Site'
|
||||
contentDir = 'content'
|
||||
enableEmoji = true
|
||||
|
||||
[module]
|
||||
# uncomment line below for temporary local development of module
|
||||
# or when using a 'theme' as a git submodule
|
||||
replacements = "github.com/colinwilson/lotusdocs -> lotusdocs"
|
||||
[[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
|
||||
```
|
||||
|
||||
### Install Locally
|
||||
|
||||
There may be cases where you prefer to customize and maintain the Lotus Docs theme yourself. In such cases, use `git` to clone the theme into the `themes/lotusdocs` directory:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/colinwilson/lotusdocs themes/lotusdocs
|
||||
```
|
||||
|
||||
Edit the `hugo.toml` config file:
|
||||
|
||||
```toml
|
||||
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 = "github.com/colinwilson/lotusdocs -> lotusdocs"
|
||||
[[module.imports]]
|
||||
path = "github.com/colinwilson/lotusdocs"
|
||||
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:
|
||||
|
||||
```shell
|
||||
hugo new docs/example-page.md
|
||||
```
|
||||
|
||||
This will create a markdown file named `example-page.md` with the following default front matter:
|
||||
|
||||
```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
|
||||
---
|
||||
```
|
||||
|
||||
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 Lotus Docs site using the `huge server` command:
|
||||
|
||||
```shell
|
||||
hugo server -D
|
||||
```
|
||||
|
||||
Navigate to `localhost:1313/docs/` and you should see a card link to the **Example Page** created earlier:
|
||||
|
||||
|
||||
|
||||
## Author
|
||||
|
||||
[Colin Wilson](https://github.com/colinwilson)
|
||||
|
||||
Copyright © 2022-2025 [Colin Wilson](https://github.com/colinwilson)
|
||||
|
||||
[^1]: [Hugo Modules](https://gohugo.io/hugo-modules/)
|
||||
Reference in New Issue
Block a user