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:

1. Install Docker Desktop:

   • Install on macOS
   • Install on Linux
   • Install on Windows

2. Execute the following command from the docs folder of your clone:

   make server
   

   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.

3. Start contributing! Note that Hugo updates the rendered documentation each time you write the file.

4. Enter the following in a browser to view the website:

   http://localhost:1314

   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.

5. Use Ctrl+C to stop the local Hugo server when you are done.

6. To restart the continuous build:

   • Restart Docker-Desktop, if necessary
   • If changes have been made to the build tools:
     • make clone
     • make build
   • Run make server

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:

  grip <file>.md
  

  Point your browser at localhost:6419 to view the formatted file. The document updates automatically each time you write your changes to disk.