docs: refactor contributing guide - local building (keptn#1484)

Signed-off-by: Yash Pimple <[email protected]> Signed-off-by: Moritz Wiesinger <[email protected]> Co-authored-by: Meg McRoberts <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]>
StackScribe · Jun 19, 2023 · 8a76c62 · 8a76c62
1 parent 59c0865
commit 8a76c62
Show file tree

Hide file tree

Showing 2 changed files with 93 additions and 84 deletions.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -27,91 +27,9 @@ We were all new to this once and are happy to help you!
 
 Please check [Contribution Guidelines](content/en/contribute/docs/contribution-guidelines/_index.md).
 
-## Building the 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 set up
-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](https://docs.docker.com/desktop/install/mac-install/)
-   * [Install on Linux](https://docs.docker.com/desktop/install/linux-install/)
-   * [Install on Windows](https://docs.docker.com/desktop/install/windows-install/)
-
-1. Build the Keptn Docsy repo:
-
-   ```console
-   make build
-   ```
-
-   > **Note**
-   To utilize the `Makefile`, you must have GNU **make**
-   available on your local machine.
-   Versions are available for all the usual Operating Systems.
-
-1. Execute the following command from the `docs` folder of your clone:
-
-   ```console
-   make server
-   ```
-
-   It will continue running in its own shell.
-
-1. Start contributing!
-Note that Hugo updates the rendered documentation each time you write the file.
-
-1. Enter the following in a browser to view the website:
-
-    `http://localhost:1314/docs-dev/`
-
-   > **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.
-
-1. Use Ctrl+C to stop the local Hugo server when you are done.
-
-1. 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](https://github.com/joeyespo/grip/blob/master/README.md) 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:
-
-     ```console
-     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.
+Please check [Building the Documentation Locally](content/en/contribute/docs/local-building/index.md).
 
 ## Interacting with github
 

diff --git a/docs/content/en/contribute/docs/local-building/index.md b/docs/content/en/contribute/docs/local-building/index.md
@@ -0,0 +1,91 @@
+---
+title: Build Documentation Locally
+description: This guide explains how to create a local version of the documentation
+weight: 400
+---
+
+## 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](https://docs.docker.com/desktop/install/mac-install/)
+   * [Install on Linux](https://docs.docker.com/desktop/install/linux-install/)
+   * [Install on Windows](https://docs.docker.com/desktop/install/windows-install/)
+
+1. Build the Keptn Docsy repo:
+
+   ```shell
+   make build
+   ```
+
+   > **Note**
+   To utilize the `Makefile`, you must have GNU **make**
+   available on your local machine.
+   Versions are available for all the usual Operating Systems.
+
+1. Execute the following command from the `docs` folder of your clone:
+
+   ```shell
+   make server
+   ```
+
+   It will continue running in its own shell.
+
+1. Start contributing!
+Note that Hugo updates the rendered documentation each time you write the file.
+
+1. Enter the following in a browser to view the website:
+
+    `http://localhost:1314/docs-dev/`
+
+   > **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.
+
+1. Use Ctrl+C to stop the local Hugo server when you are done.
+
+1. 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](https://github.com/joeyespo/grip/blob/master/README.md) 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:
+
+     ```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.