Lotus Docs | A Hugo Documentation Theme

Overview

Fri, 30 Sep 2022 05:33:22 +0100

Welcome to the Lotus Docs user guide. This guide shows you how to start creating technical documentation sites using Lotus Docs, including site customisation and using Lotus Docs’ features and templates.

What is Lotus Docs?

Lotus Docs is a theme for the Hugo static site generator (SSG), specifically designed for technical documentation sets and includes many best practices by default (The site you’re currently reading was built using the Lotus Docs theme!). Use Lotus Docs to get a working and reliable documentation site

DOCUMENTATION

Quickstart

Fri, 30 Sep 2022 05:34:22 +0100

Requirements

git
Go ≥ v1.21
Hugo ≥ v0.140.0 (Extended Version)

Install Hugo

Install the Hugo CLI, using the specific instructions for your operating system below:

Overview

Thu, 16 Nov 2023 19:49:34 +0000

The Lotus Docs theme features a built-in landing page that’s easy to customise and manage.

The landing page layout is comprised of individual sections, each with their own

LANDING PAGE

Templates
A guide to using the Lotus Docs landing page templates." data-bs-toggle="tooltip" href="https://haosend.com/docs/guides/landing-page/templates/">template. These sections are configured via a data file named landing.yaml in your /data directory.

Templates

Thu, 08 Dec 2022 19:19:31 +0000

Introduction

Each section on the landing page corresponds to a specific template with its own set of parameters for customisation. There are (currently) 4 templates.

Name	Type	Description
`hero`	hero	A basic hero template with text and CTA buttons on the left and an image on the right. Traditionally the first section of a landing page.
`feature grid`	grid	A multi row, 3 column grid listing features. Each feature consists of an icon, title, and descriptive text.
`image text`	image + text	A 2 column section with an image on the left (or the right) with some descriptive text, lists and a call-to-action button adjacent.
`image compare`	image comparison	Utilizes the image-compare-viewer library by Kyle Wetton to compare multiple before and after images. Includes an auto-generated tab to switch between image comparison sets.

notifications

Additional templates and template types are part of the Lotus Docs roadmap

Required data file parameters

For each enabled section defined in your data file (/data/landing.yaml), the following parameters are required:

Syntax Highlighting

Fri, 16 Dec 2022 01:07:15 +0000

Code Highlighters

Lotus Docs supports syntax highlighting using Prism (enabled by default via param.docs.prism in hugo.toml) or Hugo’s built-in code highlighter Chroma.

Plausible Analytics

Thu, 29 Dec 2022 16:28:15 +0000

Plausible Analytics is a simple, open source, lightweight (< 1 KB), privacy-focused alternative to Google Analytics. Plausible is completely independent, self-funded and bootstrapped. Read more about Plausible Analytics.

Google Analytics v4

Wed, 05 Jul 2023 23:48:15 +0000

Lotus Docs utilises Hugo’s internal Google Analytics v4 template¹.

info

As of July 1, 2023, UA (Universal Analytics) was deprecated, and is no longer processed by Google. Lotus Docs does not support UA.

Enabling Google Analytics

To enable Google Analytics v4, simply provide your tracking ID in your configuration file:

Feedback Widget

Tue, 08 Aug 2023 23:33:15 +0000

The Lotus Docs feedback plugin integrates with Google or Plausible Analytics allowing you to collect visitor feedback on your sites’ content.

Why use web analytics to collect feedback?

Short answer? Because it’s FREE! Other benefits include:

No need to sign up to yet another service just to collect basic visitor feedback.
Easy to configure. Once Google or Plausible Analytics (or both) are configured in hugo.toml, the Feedback Widget it ready to go.
No limit on the number of events that can be collected.

How it works

Once enabled, the feedback widget appears at bottom of every content page. Whenever a site visitor interacts with it, their feedback is collected and sent to whichever web analytics you have configured in your hugo.toml file.

FlexSearch

Tue, 20 Jun 2023 15:30:15 +0000

warning

Caution - This documentation is in progress

What is FlexSearch?

FlexSearch is a Static Search plugin that provides a fast and simple search experience for your Lotus Docs site. Static Search provides instant, dynamic results for any search terms, and includes a wealth of options and settings to fine-tune the functionality to best suit the needs of your site visitors.

How does FlexSearch work?

FlexSearch works via a mechanism known as Contextual Search (invented by Thomas Wilkerling). A Contextual Search boosts queries to a complete new level but also requires some additional memory (depending on depth). The basic idea of this concept is to limit relevance by its context instead of calculating relevance through the whole distance of its corresponding document. This way contextual search also improves the results of relevance-based queries on large Lotus Docs sites with many pages.

DocSearch

Sat, 01 Jul 2023 14:09:15 +0000

What is DocSearch?

DocSearch is a unique, free search plugin, specifically designed for technical documentation for open-source projects or technical blogs. Providing fast, accurate search options, DocSearch empowers visitors to find the information they need as quickly as possible. With the DocSearch plugin enabled, integrating search into your Lotus Docs site takes just a few moments.

KaTex

Sat, 26 Aug 2023 20:43:23 +0100

$$ f\relax{x} = \int_{-\infty}^\infty \hat f(\xi)\ e^{2 \pi i \xi x} \ d\xi $$

How to use KaTex with Lotus Docs

KaTex support is controlled by the katex parameter in your front matter (line 10 below). Add and set it to true in your front matter to enable KaTex support for that page. This means KaTex support and resources are active only for pages that require it.

Mermaid

Fri, 08 Sep 2023 06:05:19 +0100

What is Mermaid?

Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

Breadcrumb Navigation

Sun, 27 Nov 2022 07:08:15 +0000

Enable Breadcrumbs

Breadcrumb navigation is enabled by default¹ and appears in the top right-hand corner of content pages above the page title. The Lotus Docs breadcrumb implementation functions with both multilingual and single-language sites.

Structured Data

The breadcrumb navigation also auto-generates structured data for rich results to help enable search results that are more engaging to users. Here are the Breadcrumb Rich Results test results for this very page.

Link behaviour

Thu, 14 Sep 2023 19:10:58 +0100

Open external links in a new tab

By default, Lotus Docs will open external links in a new tab.

This behaviour can be disabled by setting the extLinkNewTab parameter to false in your config:

  [params.docs]
    extLinkNewTab   = false # Open external links in a new Tab? default true

      params:
        docs:
            extLinkNewTab: false # Open external links in a new Tab? default true

  {
    "params": {
        "feedback": {
            "extLinkNewTab": false
        }
    }
}

External links are indicated by the ’external link’ icon to the right of the link text. e.g. Lotus Docs GitHub repository:

Alerts

Tue, 22 Nov 2022 13:42:31 +0000

Adding a Page Alert

Page alerts can be added to your markdown using the following shortcode:

  {{< alert text="This is the default alert. It consists of a default theme colour and icon." />}}

The above code results in the following alert:

notifications

This is the default alert. It consists of a default theme colour and icon.

Alert with Context

Add context to an alert via the context parameter:

Tables

Sat, 05 Nov 2022 04:41:15 +0000

The table shortcode enables Lotus Docs to take advantage of Bootstrap’s opt-in table styling.

Regular Tables

By default Lotus Docs renders regular Markdown tables with some very basic styling:

Tabs

Tue, 25 Apr 2023 03:51:15 +0000

The tabs shortcode leverages Bootstrap’s Tabs styling to easily add Tabs to your markdown content. The shortcode is actually a combination of two separate shortcodes (tab and tabs) working together.

Prism

Mon, 28 Nov 2022 04:05:31 +0000

Prism Shortcode

When Prism is enabled in hugo.toml syntax highlighting can also be achieved using a paired Prism shortcode. The code language is declared using the lang parameter:

  {{< prism lang="html" >}}
<html>
  <head>
    <title>Buy cool new product</title>
  </head>
  <body>
    <!-- Use action="/create-checkout-session.php" if your server is PHP based. -->
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Checkout</button>
    </form>
  </body>
</html>
{{< /prism >}}

All code blocks highlighted by Prism feature the Copy to Clipboard Button plugin. Hover over (or tap if on mobile) the examples above and the copy button appears in the top right hand corner of the code block. Click this button to copy the code to your clipboard.

Markdownify

Fri, 28 Apr 2023 16:35:15 +0000

This shortcode parses its content as markdown.

Usage

The following:

  {{< markdownify >}}

**Bold Text**: Above a code block.

```html
<!-- An example HTML code block -->
<h1>Hello World</h1>

{{< /markdownify >}}

Renders:

Bold Text: Above a code block.

  <!-- An example HTML code block -->
<h1>Hello World</h1>

Nested Shortcodes

The markdownify shortcode is especially useful in cases where you require portions of content nested inside another shortcode be parsed as Markdown.

KaTex

Sun, 27 Aug 2023 04:13:11 +0100

Lotus Docs has

FEATURES

KaTex
Fast Tex math rendering for your Lotus Docs site" data-bs-toggle="tooltip" href="https://haosend.com/docs/features/katex/">built-in support for KaTex. However, there are certain equation syntaxes which do not render well if at all without a lot of character escaping¹ or alterations. The KaTex shortcode is suited to handle such cases.

GitHub Pages

Sat, 26 Aug 2023 15:36:39 +0100

Overview

GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its GitHub Pages service and automating development workflows and build with GitHub Actions.

GitLab Pages

Sat, 26 Aug 2023 15:36:47 +0100

Overview

With GitLab Pages, you can publish your Lotus Docs themed site directly from a repository in GitLab.

Use for any personal or business website.
Native support for Hugo.
Create websites for your projects, groups, or user account.
Host your site on your own GitLab instance or on GitLab.com for free.
Connect your custom domains and TLS certificates.
Attribute any license to your content.

GitLab Pages makes it easy to build, deploy, and host your Lotus Docs website.

Configuration

Sat, 21 Jan 2023 16:16:15 +0000

A list of available configuration settings in the site configuration file, hugo.toml, hugo.yaml, or hugo.json:

[params]

Google Fonts

Parameter	Type	Default Value	Description
`google_fonts`	array	N/A	An array of Google fonts and sizes to load. e.g. `google_fonts = [["Inter", "300, 400, 600, 700"],["Fira Code", "500, 700"]]` This will load the Google Inter and Fira Code fonts in the specified sizes.
`sans_serif_font`	string	System Font	Set the Sans Serif font. e.g. `"Inter"`
`secondary_font`	string	System Font	Set the Secondary font. e.g. `"Inter"`
`mono_font`	string	System Font	Set the Mono font. e.g. `"Fira Code"`

[params.footer]

Parameter	Type	Default Value	Description
`copyright`	string	N/A	Sets the footer copyright text for both the landing page and documentation site (supports Markdown)
`version`	boolean	`false`	Display the site’s truncated `git` commit hash in the footer? TBC

[params.social]

Social links are displayed as icons in the top left corner of the Lotus Docs theme. This goes for the landing page and docs site.

How to Contribute

Wed, 19 Oct 2022 21:49:38 +0100

Contribute to code

Create a Pull Request

Follow the GitHub flow.
Follow the Conventional Commits Specification

Improve documentation

Follow the GitHub flow.
Follow the Conventional Commits Specification

Create an issue

Help others

Lotus Docs Discussions is the place to get help and help others with Lotus Docs.

Financial Contributions

Wed, 19 Oct 2022 07:07:38 +0100

We use Open Collective to receive contributions, share our budget, and manage expenses. Visit the Lotus Labs Open Collective page.

Code of Conduct

Sat, 15 Oct 2022 02:21:15 +0000

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Troubleshooting

Thu, 12 Nov 2020 15:22:20 +0100

warning

Caution - This documentation is in progress

FAQ

Tue, 06 Oct 2020 08:49:31 +0000

warning

Caution - This documentation is in progress

Lotus Docs | A Hugo Documentation Theme

Overview

What is Lotus Docs? link

Quickstart

Requirements link

Install Hugo link

Overview

Templates

Introduction link

Required data file parameters link

Syntax Highlighting

Code Highlighters link

Plausible Analytics

Google Analytics v4

Enabling Google Analytics link

Feedback Widget

Why use web analytics to collect feedback? link

How it works link

FlexSearch

What is FlexSearch? link

How does FlexSearch work? link

DocSearch

What is DocSearch? link

KaTex

How to use KaTex with Lotus Docs link

Mermaid

What is Mermaid? link

Breadcrumb Navigation

Enable Breadcrumbs link

Structured Data link

Link behaviour

Open external links in a new tab link

Alerts

Adding a Page Alert link

Alert with Context link

Tables

Regular Tables link

Tabs

Prism

Prism Shortcode link

Markdownify

Usage link

Nested Shortcodes link

KaTex

GitHub Pages

Overview link

GitLab Pages

Overview link

Configuration

[params] link

Google Fonts link

[params.footer] link

Footer link

[params.social] link

How to Contribute

Contribute to code link

Create a Pull Request link

Improve documentation link

Create an issue link

Help others link

Financial Contributions

Code of Conduct

Our Pledge link

Troubleshooting

FAQ

What is Lotus Docs?

Requirements

Install Hugo

Introduction

Required data file parameters

Code Highlighters

Enabling Google Analytics

Why use web analytics to collect feedback?

How it works

What is FlexSearch?

How does FlexSearch work?

What is DocSearch?

How to use KaTex with Lotus Docs

What is Mermaid?

Enable Breadcrumbs

Structured Data

Open external links in a new tab

Adding a Page Alert

Alert with Context

Regular Tables

Prism Shortcode

Usage

Nested Shortcodes

Overview

Overview

[params]

Google Fonts

[params.footer]

Footer

[params.social]

Contribute to code

Create a Pull Request

Improve documentation

Create an issue

Help others

Our Pledge