The dev docs are managed by a static site generator called Hugo.
Working with hugo requires you to learn the hugo generator system. When creating more docs you can follow the hugo docs for more information.
In order to maintain we have forked the the hugo docs theme and replaced with the logicminds brand colors, fonts and images. You can work directly with this theme here.
The usage of this theme with regards to these docs will be as a git submodule. Please be aware of this. If you are unfamilar with git submodules I would recommend spending the time to read this article about its usage.
In order to get started with writing docs or updating the site navigation you first need to clone this repo and perform the following steps.
- install hugo
git clone https://gitlab.com/git submodule update --initcdhugo
If successful you should see:
~/logicminds/logicminds-dev-docs$ hugo
| EN
+------------------+----+
Pages | 76
Paginator pages | 0
Non-page files | 0
Static files | 93
Processed images | 0
Aliases | 34
Sitemaps | 1
Cleaned | 0
Total in 86 ms
There will be a time when the logicminds hugo theme requires an update. In order to update you will need to run the following command:
git submodule update
You can perform this at any time.
Make sure you read this article for further information.
The docs are layed out with a few different menus. First, there is the top nav bar menu. Some of the links that exist there are just placeholders so if something needs to be added or removed. This menu is considered the global menu, as noted in the config.toml file with [[menu.global]]
Each main page of the global menu has its own menu system as well. Btw, this is often referred as the taxonomy. As an example you can see the main menu system here:
[[menu.docs]]
name = "Getting Started"
weight = 1
identifier = "getting-started"
url = "/getting-started/"
In this example the menu.docs site menu has a link to the getting-started page.
These docs are all stored under the content directory.
I have created an archetype for generating a new doc. Essentially, this is just a template so we can easily create or modify archetypes.
hugo new -k doc_section en/<topic>/<subtopic>/_index.md
ie. hugo new -k doc_section en/communication/irc/_index.md
So when you want to create a new topic this is all that is required. After you create this file, you just need to add the markdown content in the _index.md file.
Also keep in mind there are some cool snippets you can use in your content. Please see the shortcodes for more info
You can run the hugo site generator at any time to ensure your docs do not contain errors.
hugo
To see the docs website you can run docs serve which generates the docs and starts a webserver. This is also a good way to develop too since hugo adds file watchers and re-generates the static content as you modify it. This is all done live so no need to restart hugo serve.
~/logicminds/logicminds-dev-docs master ● hugo serve
| EN
+------------------+----+
Pages | 76
Paginator pages | 0
Non-page files | 0
Static files | 93
Processed images | 0
Aliases | 34
Sitemaps | 1
Cleaned | 0
Total in 44 ms
Watching for changes in /logicminds/logicminds-dev-docs/{content,data,themes}
Watching for config changes in /logicminds/logicminds-dev-docs/config.toml
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/logicminds-dev-docs/ (bind address 127.0.0.1)
Press Ctrl+C to stop
docker run -ti --rm -v ${PWD}:/app --workdir=/app tmaier/markdown-spellcheck:latest -a -n --en-us content/**/*.md
--report "content/**/*.md" --ignore-acronyms --ignore-numbers --en-us