The idea is to have a completely static website that is portable and can be hosted anywhere without overhead and risks of maintaing secure LAMP stack. It is also good that the content would be living in plain text files like dokuwiki. At the same time, we'd want to have an easy to use CMS with something like Markdown syntax (and without the need to learn any web tools like Jekyll).
The Hugo [https://gohugo.io] satisfies our needs. Shadocs theme seems to be the way to do documentation websites.
Conventions:
- To be able to host it on an existing website without interfering with the existing frontpage, ontent is the site's root path for the content.
- Generally, conventions live in config.toml. We have for now opted for autogenerating the content menu rather than using static one.
- Because content is autogenerated, it should be simple to add pages by dropping new something.md with a proper header (with Weight set; see the example site pages).
- Images, PDFs, PPTs, ... etc. go to the /static.
The Hugo version to work is 0.62.2, extended. On CentOS7 it requires modules for GCC 9.2 and git 2.x loaded, because of the obsolete nature of RedHat distributions; Ubuntu 16.+ works as is, and probably on MacOS X.
When the above requirements are satisfied, here is how to get started.
-
Get the Hugo (then unpack and place the hugo binary in yout PATH:
wget https://github.com/gohugoio/hugo/releases/download/v0.62.2/hugo_extended_0.62.2_Linux-64bit.tar.gz
-
Clone this repository recursively, to get Alex Shpak's Book theme.
git clone https://github.com/um-grex/grex-docs.git --recursive
-
Change to the repository and render it with hugo.
hugo -D --theme=book server
-
Connect a local browser to port :1313 as directed by hugo and observe the rendered website.
-
Deploy the ./public directory somewhere, somehow. Can be a local server with rsync or github.io site. There is documentation on the Hugo website.
Submodules can be updated somehow when the theme updates. A nice feature of the Book theme is that the pages can be edited right in this source repository, by using the Edit link an the bottom on the rendered website. However it is still necessary and good to pull and render the website with local Hugo process, because Hugo's Golang modules and shorthands are a superset of the Git's markdown syntax, and not all of them are rendered on the github repository pages.
https://learnxinyminutes.com/docs/markdown/
Conventions for writing the documentation pages we know of.
- command line commands should be on a separate line, and quoted with
triple backticks - code, job scripts and such should use highlight shortcode for the appropriate language (like, bash)