This guide explains how to create a local version of the documentation
Build Documentation Locally
Building the documentation locally
You can run Docsy locally so that you can view the formatted version of what you are writing before you push it to github. We provide a Docsy run environment in a Docker container, which simplifies the setup and makes it easier to upgrade your local build environment as the software is updated.
To set up a local Docsy build:
Install Docker Desktop:
Execute the following command from the
docsfolder of your clone:
It will continue running in its own shell.
Note To utilize the
Makefile, you must have GNU make available on your local machine. Versions are available for all the usual Operating Systems.
Start contributing! Note that Hugo updates the rendered documentation each time you write the file.
Enter the following in a browser to view the website:
Note By default, Hugo serves the local docs on port 1313. We have modified that port for the lifecycle-toolkit docs to avoid conflicts with the keptn.github.io docs, which use port 1313 for local builds.
Use Ctrl+C to stop the local Hugo server when you are done.
To restart the continuous build:
- Restart Docker-Desktop, if necessary
- If changes have been made to the build tools:
- make clone
- make build
Building markdown files without Hugo
The Hugo generator described above only renders the markdown files under the /content/docs directory. If you need to render another markdown file (such as this CONTRIBUTING.md file) to check your formatting, you have the following options:
If you are using an IDE to author the markdown text, use the markdown preview browser for the IDE.
You can push your changes to GitHub and use the GitHub previewer (View Page).
You can install and use the grip previewer to view the rendered content locally. When grip is installed, you can format the specified file locally by running the following in its own shell:
Point your browser at
localhost:6419to view the formatted file. The document updates automatically each time you write your changes to disk.