Documentation Writing
To write the documentation we use Emacs Org-Mode. The files are created under doc/content. We use Hugo to create a static website from the org files. You do this locally and can track your changes with a web browser. If you want the changes to take effect on the web server as well, then the changes of the repository are published on github (push). Via a so called webhook the webserver will be notified which will then fetch the changes of the repository and calls Hugo to recompile the website. After that the changes are available in the www net.
Repository
Cloning the repository
This step must be done only the very first time! With https:
git clone https://github.com/nodecum/nodecum-learning.git
or if you want to pass on changes with ssh:
git clone git@github.com:nodecum/nodecum-learning.git
We have to update the submodules it contains too:
cd nodecum-learning
git submodule update --init --recursive
Update the repository
Before you make changes it is advisable to get the current state.
cd nodecum-learning
git pull
Org-Mode
When generating the documentation the org files are parsed by go-org which is a part of Hugo. See go-org doc for supported org features.
Hugo
Hugo is a static website generator. This means the source files (in our case they are in the .org format) are converted to HTML files, which then represent the web pages.
installation
snap install hugo --channel=extended
Compile
To get a local web server which automatically updates to the last changed page:
cd nodecum-learning/doc
hugo server --navigateToChanged
after that you can point your webbrowser to the address http://localhost:1313 to view
the web page. Every time you save an .org
file in the directory content/
this will cause a recompilation of the corresponding HTML file.