A guide to getting up and running with Lotus Docs.
- Go ≥ v1.19
- Hugo ≥ v0.117.0 (Extended Version)
Install the Hugo CLI, using the specific instructions for your operating system below:
The Hugo GitHub repository contains pre-built versions of the Hugo command-line tool for various operating systems, which can be found on the Releases page
For more instruction on installing these releases, refer to Hugo’s documentation
Create a New Lotus Docs Site
With Hugo installed, create a new Hugo project using the
hugo new command:
hugo new site my-docs-site && cd my-docs-site
Now initialize your project as a Hugo Module using the
hugo mod init command:
hugo mod init my-docs-site
hugo mod init github.com/<user>/<my-docs-site>/.
You can now choose your preferred method for adding the Lotus Docs theme to your new site from the options below:
Create New Content
Navigate to the root of your Hugo project and use the
hugo new command to create a file in the
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 options to suit your needs.
The code below shows the front matter code used to create this page, along with a portion of markdown from the body:
+++ weight = 100 date = "2023-05-03T22:37:22+01:00" draft = true author = "Colin Wilson" title = "Quickstart" icon = "rocket_launch" toc = true description = "A quickstart guide to creating new content in Lotus Docs" publishdate = "2023-05-03T22:37:22+01:00" tags = ["Beginners"] +++ ## 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/examplepage.md ``` ...
Preview your Site
Now that you’ve created some sample content you can preview your new Lotus Docs site using the
huge server command:
hugo server -D
localhost:1313/docs/ and you should see a card link to the Example Page created earlier:
Lotus Docs uses a simple weighting method for ordering content and creating menus.
The front matter
weight variable is used to order all content and auto-generate the menu structure (including the sidebar menu and page navigation buttons). Lower weight values take higher precedence. So content with lower weights come first and are so ordered in the menu.
As mentioned, Lotus Docs auto-generates menus and navigation links using the front matter weight variable. For example, Navigate to the
content/docs directory and create two content files,
doc-two.md, then edit the weight values to
100. This ensures plenty of room to insert new posts between existing items should you need to.
Your directory structure should now look like this:
content/ └── docs/ ├── doc-one.md └── doc-two.md
Links to both posts are now visible in the sidebar menu where
doc-one.md will come before and be placed above
hugo.tomlas opposed to an auto-generated one is part of the Lotus Docs roadmap.
Second Level Menu Items
Second level menu items can be generated by first creating a ‘parent’ directory containing an
_index.md file, e.g.:
hugo new docs/parent-directory/_index.md
The above command creates an
_index.md file inside a directory named
content/ └── docs/ ├── parent-directory/ │ └── _index.md ├── doc-one.md ├── doc-two.md └── _index.md
You can now create second level items inside the
parent-directory as normal. Run the
hugo new command again to create a post inside the newly created
hugo new docs/parent-directory/doc-three.md
Your directory/file structure should now look like this:
content/ └── docs/ ├── parent-directory/ │ ├── _index.md │ └── doc-three.md ├── doc-one.md ├── doc-two.md └── _index.md
This is reflected in the sidebar menu with
parent-directory functioning as a dropdown menu containing a link to the Doc Three post:
Last updated 02 Oct 2023, 16:33 +0100 .