docs: use GitHub alerts instead of mkdocs admonitions (#592)

crenshaw-dev · web-flow · commit cc4a08de01fd · 2025-10-16T15:59:50.000-05:00
* docs: use GitHub alerts instead of mkdocs admonitions

Signed-off-by: Michael Crenshaw &lt;350466+crenshaw-dev@users.noreply.github.com&gt;

* add back the thing copilot removed

Signed-off-by: Michael Crenshaw &lt;350466+crenshaw-dev@users.noreply.github.com&gt;

* fix ci order

Signed-off-by: Michael Crenshaw &lt;350466+crenshaw-dev@users.noreply.github.com&gt;

---------

Signed-off-by: Michael Crenshaw &lt;350466+crenshaw-dev@users.noreply.github.com&gt;
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -214,6 +214,31 @@ make docker-build
 - If deepcopy methods are missing, run `make generate`
 - If UI builds fail, check Node.js version and run `npm install` in the UI directory
 
+# Setting up MkDocs and Python Virtual Environment
+
+To build and serve documentation locally, set up a Python virtual environment at the repository root:
+
+```fish
+python3 -m venv .venv
+source .venv/bin/activate.fish
+pip install -r docs/requirements.txt
+mkdocs serve
+```
+
+- This will install all MkDocs dependencies, including plugins for GitHub-style alerts.
+
+## Verifying Documentation Linting
+
+To check that your documentation changes do not introduce any MkDocs warnings, run:
+
+```bash
+make lint-docs
+```
+
+This will build the documentation and fail if any warnings are present. The full MkDocs output will be shown if there are issues, making it easy to debug. This check is also run automatically in CI for every pull request.
+
+Make sure you have activated your Python virtual environment and installed dependencies as described above before running this command.
+
 ## Additional Resources
 
 - Main documentation: https://gitops-promoter.readthedocs.io/
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -31,6 +31,17 @@ jobs:
           make build-extension
       - name: UI Checks
         run: make lint-ui
+      - name: Set up Python and venv for docs
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Create venv and install MkDocs requirements
+        run: |
+          python3 -m venv .venv
+          . .venv/bin/activate
+          pip install -r docs/requirements.txt
+      - name: Lint Docs
+        run: . .venv/bin/activate && make lint-docs
       - name: Get dependencies
         run: go mod download
       - name: Restore build output from cache
diff --git a/.gitignore b/.gitignore
@@ -83,3 +83,8 @@ yarn-error.log*
 
 # Built UI static files
 ui/web/static/
+
+# MkDocs build output
+mkdocs-lint.log
+# MkDocs build site directory
+site/
diff --git a/Makefile b/Makefile
@@ -298,6 +298,15 @@ $(GORELEASER): $(LOCALBIN)
 serve-docs:
 	$(CONTAINER_TOOL) run ${MKDOCS_RUN_ARGS} --rm -it -p 8000:8000 -v ${CURRENT_DIR}:/docs -w /docs --entrypoint "" ${MKDOCS_DOCKER_IMAGE} sh -c 'pip install mkdocs; pip install $$(mkdocs get-deps); mkdocs serve -a $$(ip route get 1 | awk '\''{print $$7}'\''):8000'
 
+.PHONY: lint-docs
+lint-docs:  ## Build docs and fail if there are warnings
+	@mkdocs build 2>&1 | tee mkdocs-lint.log
+	@if grep -q 'WARNING' mkdocs-lint.log; then \
+	  echo "MkDocs build produced warnings!"; \
+	  cat mkdocs-lint.log; \
+	  exit 1; \
+	fi
+
 # go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
 # $1 - target path with name of binary (ideally with version)
 # $2 - package url which can be installed
diff --git a/docs/commit-status-controllers/argocd.md b/docs/commit-status-controllers/argocd.md
@@ -5,16 +5,15 @@ based on Argo CD's concept of a healthy application. The controller listens for
 Applications based on a common label on the Application resources managed by a particular 
 PromotionStrategy.
 
-!!! important
-    Currently this controller only works with Argo CD Applications that are configured to use the [Source Hydrator](https://argo-cd.readthedocs.io/en/stable/user-guide/source-hydrator/).
+> [!IMPORTANT]
+> Currently this controller only works with Argo CD Applications that are configured to use the [Source Hydrator](https://argo-cd.readthedocs.io/en/stable/user-guide/source-hydrator/).
 
-!!! important
-    Currently the repo URL configured in the PromotionStrategy must be exactly the same as the repo URL configured in the Argo CD Application.
+> [!IMPORTANT]
+> Currently the repo URL configured in the PromotionStrategy must be exactly the same as the repo URL configured in the Argo CD Application.
 
-!!! note
-
-    GitOps Promoter provides several opt-in Argo CD integrations that improve the user experience. Check out the 
-    [Argo CD Integrations](./argocd-integrations.md) page for more information.
+> [!NOTE]
+> GitOps Promoter provides several opt-in Argo CD integrations that improve the user experience. Check out the 
+> [Argo CD Integrations](../argocd-integrations.md) page for more information.
 
 ## Example Configurations
 
@@ -61,14 +60,14 @@ spec:
 ### Commit Status URL Template
 To configure setting the url of a commit status, for example, a link to an Argo CD instance, set the `url.template` field. The template uses [Go templates](https://pkg.go.dev/text/template) syntax and most [Sprig](https://masterminds.github.io/sprig/) functions (excluding `env`, `expandenv` and `getHostByName`) are supported as well as an additional [`urlQueryEscape`](https://pkg.go.dev/net/url#QueryEscape) function for escaping url query parameters. The template receives `.Environment` and `.ArgoCDCommitStatus` variables. 
 
-!!! important 
-    The rendered URL must use a scheme of either 'http' or 'https'
+> [!IMPORTANT]
+> The rendered URL must use a scheme of either 'http' or 'https'
 
 #### Template Variables
 The following variables are available in the template:
 
 - `.Environment` - string holding the environment name (i.e. environment branch name) for the group of Applications the URL is being generated for.
-- `.ArgoCDCommitStatus` - holds the whole [CR](../../crd-specs#argocdcommitstatus) in its current state
+- `.ArgoCDCommitStatus` - holds the whole [CR](../crd-specs.md#argocdcommitstatus) in its current state
 
 #### Template Options 
 Template options can be configured for how missing variables are handled. 
@@ -130,9 +129,7 @@ To enable multi-cluster support, you need to configure two components:
    - Create a secret with key `kubeconfig` containing a standard `~/.kube/config` file as its value and label `sigs.k8s.io/multicluster-runtime-kubeconfig: "true"`
    - The secret must be created in the same namespace where gitops-promoter runs
    - The controller uses the `current context` from the kubeconfig to determine which cluster to use
-     
-    !!! note
-        Remove any additional clusters from the `kubeconfig` as they will be ignored
+   - Remove any additional clusters from the `kubeconfig` as they will be ignored
 
 #### RBAC Configuration
    - Create a ClusterRole and binding in the external cluster for the service account associated with the kubeconfig
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -36,13 +36,12 @@ During the creation the GitHub App, you will need to configure the following set
 
 ### Webhooks (Optional - but highly recommended)
 
-!!! note "Configure your webhook ingress"
-
-    We do support configuration of a GitHub App webhook that triggers PR creation upon Push. However, we do not configure
-    the ingress to allow GitHub to reach the GitOps Promoter. You will need to configure the ingress to allow GitHub to reach 
-    the GitOps Promoter via the service promoter-webhook-receiver which listens on port `3333`. If you do not use webhooks 
-    you might want to adjust the auto reconciliation interval to a lower value using these `promotionStrategyRequeueDuration` and
-    `changeTransferPolicyRequeueDuration` fields of the `ControllerConfiguration` resource.
+> [!NOTE]
+> We do support configuration of a GitHub App webhook that triggers PR creation upon Push. However, we do not configure
+> the ingress to allow GitHub to reach the GitOps Promoter. You will need to configure the ingress to allow GitHub to reach 
+> the GitOps Promoter via the service promoter-webhook-receiver which listens on port `3333`. If you do not use webhooks 
+> you might want to adjust the auto reconciliation interval to a lower value using these `promotionStrategyRequeueDuration` and
+> `changeTransferPolicyRequeueDuration` fields of the `ControllerConfiguration` resource.
 
 Webhook URL: `https://<your-promoter-webhook-receiver-ingress>/`
 
@@ -87,9 +86,8 @@ stringData:
   githubAppPrivateKey: <your-private-key>
 ```
 
-!!! note 
-
-    This Secret will need to be installed to the same namespace that you plan on creating PromotionStrategy resources in.
+> [!NOTE]
+> This Secret will need to be installed to the same namespace that you plan on creating PromotionStrategy resources in.
 
 We also need a GitRepository and ScmProvider, which is are custom resources that represents a git repository and a provider. 
 Here is an example of both resources:
@@ -118,10 +116,9 @@ spec:
     name: <your-scmprovider-name>
 ```
 
-!!! note 
-
-    The GitRepository and ScmProvider also need to be installed to the same namespace that you plan on creating PromotionStrategy 
-    resources in, and it also needs to be in the same namespace of the secret it references.
+> [!NOTE]
+> The GitRepository and ScmProvider also need to be installed to the same namespace that you plan on creating PromotionStrategy 
+> resources in, and it also needs to be in the same namespace of the secret it references.
 
 ## GitLab Configuration
 
@@ -217,9 +214,8 @@ spec:
     name: <your-scmprovider-name> # The secret that contains the GitLab Access Token
 ```
 
-!!! note 
-
-    The GitRepository and ScmProvider also need to be installed to the same namespace that you plan on creating PromotionStrategy resources in, and it also needs to be in the same namespace of the secret it references.
+> [!NOTE]
+> The GitRepository and ScmProvider also need to be installed to the same namespace that you plan on creating PromotionStrategy resources in, and it also needs to be in the same namespace of the secret it references.
 
 
 ## Promotion Strategy
@@ -244,23 +240,20 @@ spec:
     name: <git-repository-ref-name> # The name of the GitRepository resource
 ```
 
-!!! important
-
-    Each `branch` configured here is the branch that GitOps Promoter will merge into. Your [hydrator](index.md#prerequisites)
-    configuration must hydrate to these branch names, but **suffixed with `-next`**. This convention is hard-coded in
-    GitOps Promoter.
-
-    For an example of how to configure the Argo CD Source Hydrator, see the [Argo CD tutorial](tutorial-argocd-apps.md#deploy-an-application-for-3-environments).
-    (Note the difference between the `syncSource` and the `hydrateTo` fields.)
-
-!!! note 
-
-    Notice that the branches are prefixed with `environment/`. This is a convention that we recommend you follow.
+> [!IMPORTANT]
+> Each `branch` configured here is the branch that GitOps Promoter will merge into. Your [hydrator](index.md#prerequisites)
+> configuration must hydrate to these branch names, but **suffixed with `-next`**. This convention is hard-coded in
+> GitOps Promoter.
+>
+> For an example of how to configure the Argo CD Source Hydrator, see the [Argo CD tutorial](tutorial-argocd-apps.md#deploy-an-application-for-3-environments).
+> (Note the difference between the `syncSource` and the `hydrateTo` fields.)
 
-!!! note 
+> [!NOTE]
+> Notice that the branches are prefixed with `environment/`. This is a convention that we recommend you follow.
 
-    The `autoMerge` field is optional and defaults to `true`. We set it to `false` here because we do not have any
-    CommitStatus checks configured. With these all set to `false` we will have to manually merge the PRs.
+> [!NOTE]
+> The `autoMerge` field is optional and defaults to `true`. We set it to `false` here because we do not have any
+> CommitStatus checks configured. With these all set to `false` we will have to manually merge the PRs.
 
 ## Launching the UI
 
diff --git a/docs/monitoring/metrics.md b/docs/monitoring/metrics.md
@@ -2,10 +2,9 @@
 
 GitOps Promoter produces metrics counter and histogram metrics for all network-bound operations.
 
-!!!important "Metrics Subject to Change"
-
-    The metrics produced by GitOps Promoter are subject to change as the project evolves until the 1.0 release. 
-    Please refer to this document for the latest metrics.
+> [!IMPORTANT]
+> The metrics produced by GitOps Promoter are subject to change as the project evolves until the 1.0 release. 
+> Please refer to this document for the latest metrics.
 
 ## git_operations_total
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -5,3 +5,4 @@ mkdocs-material==9.5.42
 mkdocs-material-extensions==1.3.1
 pygments==2.18.0
 mkdocs-redirects==1.2.2
+mkdocs-github-admonitions-plugin==0.1.1
diff --git a/docs/tutorial-argocd-apps.md b/docs/tutorial-argocd-apps.md
@@ -19,20 +19,18 @@ To complete this tutorial, you will need the following:
 * [A GitHub Account](https://github.com/)
 * [Git](https://git-scm.com/)
 
-!!! note
-
-    GitOps Promoter provides several opt-in Argo CD integrations that improve the user experience. Check out the 
-    [Argo CD Integrations](./argocd-integrations.md) page for more information.
+> [!NOTE]
+> GitOps Promoter provides several opt-in Argo CD integrations that improve the user experience. Check out the 
+> [Argo CD Integrations](./argocd-integrations.md) page for more information.
 
 ## Set up the test cluster
 
 ### Create the cluster
 
 If you don't have a test cluster yet, create one. With kind, simply run `kind create cluster`
 
-!!! tip "Alternatively"
-
-    You can name the cluster with `kind create cluster --name promoter`
+> [!TIP]
+> You can name the cluster with `kind create cluster --name promoter`
 
 Confirm that your access works with `kubectl get nodes`. Nodes should have a name starting with the name of your cluster (per example: `promoter-control-plane`)
 
@@ -71,9 +69,8 @@ Connect with this password for the `admin` user.
 kubectl apply -f https://github.com/argoproj-labs/gitops-promoter/releases/download/v0.14.0/install.yaml
 ```
 
-!!! note
-
-    You may want to run the command twice to deploy the controller configuration after the CRDs were deployed.
+> [!NOTE]
+> You may want to run the command twice to deploy the controller configuration after the CRDs were deployed.
 
 ## Set up a sample repository
 
@@ -110,17 +107,16 @@ However, we are running the workload locally and the webhook is not required for
 
 If you want to set up the webhook, read [Getting started](./getting-started.md) and try to use [https://smee.io/](https://smee.io/).
 
-!!! tip "Alternatively"
-
-    You can adjust the setting down to something like 15 or 30 seconds.
-
-    See the [default config](https://github.com/argoproj-labs/gitops-promoter/blob/65d5905c51acac5d1caf3af01ceb0747795207e5/config/config/controllerconfiguration.yaml#L14-L17) for the config location.
-
-    ```shell
-    kubectl patch -n promoter-system controllerconfiguration promoter-controller-configuration \
-      --type merge \
-      -p '{"spec": {"promotionStrategyRequeueDuration": "30s", "changeTransferPolicyRequeueDuration": "30s", "argocdCommitStatusRequeueDuration": "30s", "pullRequestRequeueDuration": "30s"}}'
-    ```
+> [!TIP]
+> You can adjust the setting down to something like 15 or 30 seconds.
+>
+> See the [default config](https://github.com/argoproj-labs/gitops-promoter/blob/65d5905c51acac5d1caf3af01ceb0747795207e5/config/config/controllerconfiguration.yaml#L14-L17) for the config location.
+>
+> ```shell
+> kubectl patch -n promoter-system controllerconfiguration promoter-controller-configuration \
+>   --type merge \
+>   -p '{"spec": {"promotionStrategyRequeueDuration": "30s", "changeTransferPolicyRequeueDuration": "30s", "argocdCommitStatusRequeueDuration": "30s", "pullRequestRequeueDuration": "30s"}}'
+> ```
 
 #### Generate a key
 
@@ -216,10 +212,9 @@ If you go to the Argo CD UI, in the applications, you should now see the "SOURCE
 
 It should have the message "from HEAD (...) to environment/development-next (...)"
 
-!!! important
-
-    The Application will have an error under "APP CONDITIONS" that "app path does not exist." That's because the
-    Promoter has not yet moved the hydrated manifests to the syncSource branches. That's the next step.
+> [!IMPORTANT]
+> The Application will have an error under "APP CONDITIONS" that "app path does not exist." That's because the
+> Promoter has not yet moved the hydrated manifests to the syncSource branches. That's the next step.
 
 This means three things in case of a change in the main branch:
 
@@ -322,16 +317,14 @@ Here, we implement a simple strategy:
 2. Auto-merge on staging (if development is successful)
 3. Manual merge on production
 
-!!! note
-
-    You should see 2 PRs getting merged automatically and 1 PR to merge manually for the production. That is normal: we branched from the main branch wich is DRY. The promoter detects change and do what's needed to sync the two branches.
+> [!NOTE]
+> You should see 2 PRs getting merged automatically and 1 PR to merge manually for the production. That is normal: we branched from the main branch wich is DRY. The promoter detects change and do what's needed to sync the two branches.
 
 ## Play with your environment
 
 We deployed the application "helm-guestbook" from the example repository.
 
 Try editing the main branch: number of replicas, helm templates... And see the PRs getting promoted from development to staging, then wait for your approval for the prod.
 
-!!! note
-
-    Since we are not using the webhook. It can takes 5 to 15 minutes to complete the cycle unless you've set the requeue duration to a lower value.
+> [!NOTE]
+> Since we are not using the webhook. It can takes 5 to 15 minutes to complete the cycle unless you've set the requeue duration to a lower value.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -42,6 +42,7 @@ nav:
       - Argo CD Apps: tutorial-argocd-apps.md
   - Argo CD Integrations: argocd-integrations.md
 plugins:
+  - gh-admonitions
   - redirects:
       redirect_maps:
         'metrics.md': 'monitoring/metrics.md' # Page was moved to a subdirectory.
