Updates contributing docs

README.md

@@ -20,18 +20,16 @@ updates:
 
 1. Fork [olm-docs](https://github.com/operator-framework/olm-docs) on GitHub.
 1. Make your changes and send a pull request (PR).
-1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
-it's a work in progress. (**Don't** add the Hugo property
-"draft = true" to the page front matter, because that prevents the
-auto-deployment of the content preview described in the next point.)
+1. If you're not yet ready for a review, create a draft PR to indicate it's a work in progress. (**Don't** add the Hugo property
+  "draft = true" to the page front matter, because that prevents the
+  auto-deployment of the content preview described in the next point.)
 1. Wait for the automated PR workflow to do some checks. When it's ready,
-you should see a comment like this: **deploy/netlify — Deploy preview ready!**
+  you should see a comment like this: **deploy/netlify — Deploy preview ready!**
 1. Click **Details** to the right of "Deploy preview ready" to see a preview
-of your updates.
+  of your updates.
 1. Continue updating your doc and pushing your changes until you're happy with
-the content.
-1. When you're ready for a review, add a comment to the PR, and remove any
-"WIP" markers.
+  the content.
+1. When you're ready for a review, remove any "WIP" markers and mark PR ready for review.
 
 ## Updating a single page
 
@@ -43,52 +41,12 @@ If you've just spotted something you'd like to change while using the docs, Docs
 
 ## Previewing your changes locally
 
-If you want to run your own local Hugo server to preview your changes as you work:
-
-1. Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS.
-1. Fork [olm-docs](https://github.com/operator-framework/olm-docs), then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
-
-```sh
-git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
-```
-
-1. Run `hugo server` in the site root directory. By default your site will be available at <http://localhost:1313/>. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
-1. Continue with the usual GitHub workflow to edit files, commit them, push the
-changes up to your fork, and create a pull request.
+If you want to run your own local Hugo server to preview your changes as you work follow [this guide](/content/en/docs/contribution-guidelines/local-docs.md).
 
 ## Creating an issue
 
 If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [olm-docs repo](https://github.com/operator-framework/olm-docs). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
 
-## Local Development
-
-Clone the repository:
-
-```sh
-git clone https://github.com/operator-framework/olm-docs/
-```
-
-The docs are built with [Hugo](https://gohugo.io/) which can be installed along with the
-required extensions by following the [docsy install
-guide](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation).
-
-We use `git submodules` to install the docsy theme. From the
-root directory, update the submodules to install the theme.
-
-```sh
-git submodule update --init --recursive
-```
-
-## Build and Serve
-
-You can build and serve your docs to localhost:1313 with:
-
-```sh
-hugo server
-```
-
-Any changes will be included in real time.
-
 ## Useful resources
 
 * [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.

assets/scss/_docs.scss

@@ -21,6 +21,10 @@
         list-style: disc;
         margin-left: 2rem;
     }
+    ol {
+        list-style: decimal;
+        margin-left: 2rem;
+    }
    .td-sidebar-nav .td-sidebar-link__page {
         font-weight: normal;
     }

content/en/docs/contribution-guidelines/_index.md

@@ -24,48 +24,36 @@ Here's a quick guide to updating the docs. It assumes you're familiar with the
 GitHub workflow and you're happy to use the automated preview of your doc
 updates:
 
-- Fork [olm-docs](https://github.com/operator-framework/olm-docs) on GitHub.
-- Make your changes and send a pull request (PR).
-- If you're not yet ready for a review, add "WIP" to the PR name to indicate
-  it's a work in progress. (**Don't** add the Hugo property
+1. Fork [olm-docs](https://github.com/operator-framework/olm-docs) on GitHub.
+1. Make your changes and send a pull request (PR).
+1. If you're not yet ready for a review, create a draft PR to indicate it's a work in progress. (**Don't** add the Hugo property
   "draft = true" to the page front matter, because that prevents the
   auto-deployment of the content preview described in the next point.)
-- Wait for the automated PR workflow to do some checks. When it's ready,
+1. Wait for the automated PR workflow to do some checks. When it's ready,
   you should see a comment like this: **deploy/netlify — Deploy preview ready!**
-- Click **Details** to the right of "Deploy preview ready" to see a preview
+1. Click **Details** to the right of "Deploy preview ready" to see a preview
   of your updates.
-- Continue updating your doc and pushing your changes until you're happy with
+1. Continue updating your doc and pushing your changes until you're happy with
   the content.
-- When you're ready for a review, add a comment to the PR, and remove any
-  "WIP" markers.
+1. When you're ready for a review, remove any "WIP" markers and mark PR ready for review.
 
 ## Updating a single page
 
 If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
 
-- Click **Edit this page** in the top right hand corner of the page.
-- If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
-- Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make, preview, and propose your changes.
+1. Click **Edit this page** in the top right hand corner of the page.
+1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
+1. Follow the rest of the [Quick start with Netlify](#quick-start-with-netlify) process above to make, preview, and propose your changes.
 
 ## Previewing your changes locally
 
-If you want to run your own local Hugo server to preview your changes as you work:
-
-- Follow the instructions in [Getting started](/docs/getting-started) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS.
-- Fork [olm-docs](https://github.com/operator-framework/olm-docs), then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
-
-```bash
-git clone --recurse-submodules --depth 1 https://github.com/google/docsy-example.git
-```
-
-- Run `hugo server` in the site root directory. By default your site will be available at http://localhost:1313. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
-- Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.
+If you want to run your own local Hugo server to preview your changes as you work follow [this guide](/docs/contribution-guidelines/local-docs/).
 
 ## Creating an issue
 
 If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [olm-docs repo](https://github.com/operator-framework/olm-docs). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
 
 ## Useful resources
 
-- [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.
-- [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.
+* [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.
+* [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.

content/en/docs/contribution-guidelines/local-docs.md

@@ -5,52 +5,47 @@ linkTitle: Local Docs
 
 ## Prerequisites
 
-Clone the repository:
+For running local dev server you will only need to install stable version of [Go](https://go.dev/)
+and clone the repository:
 
 ```bash
 git clone https://github.com/operator-framework/olm-docs/
 ```
 
-The docs are built with [Hugo](https://gohugo.io/) which can be installed along with the
-required extensions by following the [docsy install
-guide](https://www.docsy.dev/docs/getting-started/).
+For other tasks such as building production version of the site
+and linting you will also need to:
+* Install Node.js LTS
+* Install Docker or Podman
 
-We use `git submodules` to install the docsy theme. From the
-root directory, update the submodules to install the theme.
-
-```bash
-git submodule update --init --recursive
-```
 
 ## Build and Serve
 
-You can build and serve your docs to localhost:1313 with:
+You can build and serve your docs to <http://localhost:1313/> with:
 
 ```bash
-hugo server
+make serve
 ```
 
 Any changes will be included in real time.
 
 ## Running the Linting Script Locally
 
-The `hack/ci/link-check.sh` script is responsible for building the site and running [html-proofer](https://github.com/gjtorikian/html-proofer) that validates the generated HTML output.
-
-Before running the linting script, ensure you have the correct environment variable sets locally:
+To run linting locally you will need to run the following command:
 
-- `$CONTAINER_ENGINE`: controls what container engine will be used. Defaults to `docker`.
-- `$CONTAINER_RUN_EXTRA_OPTIONS`: allows you to specify any additional run options to the container engine. Defaults to an empty string.
+```bash
+make lint
+```
 
-In order to run the linting script locally using `podman`, run the following command from the root directory:
+This assumes `docker` command is available. If you want to specify different engine such as `podman`:
 
 ```bash
-export CONTAINER_ENGINE="podman"
-${PWD}/hack/ci/link-check.sh
+make lint CONTAINER_ENGINE=podman
 ```
 
+Behind this target, the `hack/ci/link-check.sh` script is responsible for running [html-proofer](https://github.com/gjtorikian/html-proofer) that validates the generated HTML output.
+
 **Note**: In the case you're getting permission denied errors when reading from that mounted volume, set the following environment variable and re-run the linting script:
 
 ```bash
-export CONTAINER_RUN_EXTRA_OPTIONS="--security-opt label=disable"
-${PWD}/hack/ci/link-check.sh
+make lint CONTAINER_RUN_EXTRA_OPTIONS="--security-opt label=disable"
 ```

hack/ci/link-check.sh

@@ -7,4 +7,5 @@ CONTAINER_ENGINE=${CONTAINER_ENGINE:="docker"}
 # ignore
 # 1: links going back to help.github.com are rate-limited and can make this flaky
 # 2: docsy autogenerated edit links to original markdown source, which will fail if the markdown file is new
-${CONTAINER_ENGINE} run --rm -v $(pwd)/public:/target mtlynch/htmlproofer /target --ignore-empty-alt --ignore-status-codes 429 --allow-hash-href --no-check-external-hash --ignore-urls '/help.github.com/,/edit\/master\/.*\.md/,/tree\/master\/.*\.md/,/new\/master\/.*filename=change-me\.md/'
+# 3: ignore localhost link to a hugo site
+${CONTAINER_ENGINE} run --rm -v $(pwd)/public:/target mtlynch/htmlproofer /target --ignore-empty-alt --ignore-status-codes 429 --allow-hash-href --no-check-external-hash --ignore-urls '/help.github.com/,/edit\/master\/.*\.md/,/tree\/master\/.*\.md/,/new\/master\/.*filename=change-me\.md/,/localhost:1313/'