Documentation
The documentation that you see here is powered by Docusaurus. The websites states:
Docusaurus is a project for building, deploying, and maintaining open source project websites easily.
- Docusaurus
With a solution like this, you can place your documentation right next to your code. In addition you can use feature like GitHub Pages or GitLab Pages to host the content of your documentation. This simplifies your workflow and allows you to have the same tooling and process for you documentation as for your code.
In this repository, you can find the documentation in the _docs folder.
GitHub Pages​
For this project, we are using GitHub Pages to host the documentation.
There are two main parts that need to be done. First you need to build and
deploy the page. And second you need to configure GitHub pages. For the first
part, we use GitHub Actions. We have two
workflows, that will run when there are changes to the _docs folder.
This workflow runs with every push to the
mainbranch. It builds and deploys the documentationThis workflow runs when there is a pull requests to the
mainbranch. It builds the documentation, to see whether there are any errors in the changes.
The second part is to configure GitHub Pages. This can be done in the Settings -> Pages of your project. I won't paste the link, as you don't have access to that page.
Custom Domain​
On the settings site, you can also configure a Custom Domain with which the page can be accessed. In order to use a custome domain, you need to configure your DNS server accordingly. As you can imagine, we are doing this also with terraform. You can find the code for the Route53 record here and the module here.
danger
Instead of configuring the Custom Domain on the settings page, I added the
CNAME file in the
_docs/static-folder.
This file contains the custom domain name, and needs to be part of the content
of your page. If you don't have this file here, then you need to add the domain
manually after each deployment.
Plugins​
One problem with documentation is to keep it up to date. One very nice feature, I really like, is to link code snippets into the documentation. Docusaurus sadly doesn't have this feature by default. Luckily someone else solved that for us and created the Docusaurus Theme GitHub Codeblock plugin. With this plugin you can include code as follows:
```terraform reference
https://github.com/elft3r/example-voting-app/blob/main/infrastructure-live/dev/eu-central-1/data-stores/ecr/terragrunt.hcl#L26-L35
```