Make docs compatible with the developer guide

.devcontainer/Dockerfile

@@ -4,6 +4,9 @@ RUN apt-get update \
     && apt-get install -y --no-install-recommends python3-pip \
     && rm -rf /var/lib/apt/lists/*
 
+RUN yarn global add \
+    markdownlint-cli2 markdown-it-admon
+
 COPY docs/requirements.txt docs/requirements.txt
 
 RUN pip install --break-system-packages -r docs/requirements.txt

.github/workflows/docs.yaml

@@ -5,6 +5,33 @@ on:
   pull_request:
 
 jobs:
+  lint:
+    # pull requests are a duplicate of a branch push if within the same repo.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.1.1
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Set node
+        uses: actions/setup-node@v4.0.0
+        with:
+          node-version: 18
+
+      - name: Install yarn dependencies
+        uses: borales/actions-yarn@v4.2.0
+        with:
+          cmd: global add markdownlint-cli2 markdown-it-admon
+
+      - name: Lint with markdownlint-cli2
+        run: >
+          markdownlint-cli2
+          *.{md,markdown}
+          docs/**/*.{md,markdown}
+
   build:
     # pull requests are a duplicate of a branch push if within the same repo.
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository

.markdownlint-cli2.jsonc

@@ -0,0 +1,9 @@
+{
+  "config": {
+    "MD013": false,
+    "MD046": {
+      "style": "fenced"
+    }
+  },
+  "markdownItPlugins": [["markdown-it-admon"]]
+}

README.md

@@ -2,12 +2,12 @@
 
 The Diamond Light Source developer portal, built with backstage for deployment on kubernetes.
 
-|                |                                                                  |
-| -------------- | ---------------------------------------------------------------- |
-| Source Code    | https://github.com/DiamondLightSource/developer-portal           |
-| User Docs      | https://diamondlightsource.github.io/developer-portal/user/      |
-| Developer Docs | https://diamondlightsource.github.io/developer-portal/developer/ |
-| Releases       | https://github.com/DiamondLightSource/developer-portal/releases  |
+|                |                                                                    |
+| -------------- | ------------------------------------------------------------------ |
+| Source Code    | <https://github.com/DiamondLightSource/developer-portal>           |
+| User Docs      | <https://diamondlightsource.github.io/developer-portal/user/>      |
+| Developer Docs | <https://diamondlightsource.github.io/developer-portal/developer/> |
+| Releases       | <https://github.com/DiamondLightSource/developer-portal/releases>  |
 
 ## Developing Locally (VSCode)
 
@@ -31,6 +31,7 @@ The Diamond Light Source developer portal, built with backstage for deployment o
   - Populating the [necessary secrets](#necessary-secrets) in their respective fields in `backend.auth`
   - Pointing to an existing secret containing the [necessary secrets](#necessary-secrets) with `backend.auth.existingSecret` (recommended)
 - Deploy the portal, with:
+
   ```sh
   cd charts/developer-portal
   helm install <deployment-name> .

docs/common/entity-dependson.md

@@ -1 +1,3 @@
+<!-- markdownlint-disable MD041 -->
+
 An array of [entity references](https://backstage.io/docs/features/software-catalog/references#string-references) to the Components and Resources that this entity depends on, e.g. `dependsOn: [component:developer-portal-backend]`. There is no requirement for these entities to be created within the same location; Existing entities can be listed in the catalog.

docs/common/entity-envelope.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD025 -->
+
 # `apiVersion` [Required]
 
 The `apiVersion` is the version of specification format for that particular entity that the specification is made against. The version is used for being able to evolve the format and to distinguish them from other types of object that share the same type of structure - e.g. Kubernetes object manifests.

docs/common/entity-owner.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD041 -->
+
 An [entity reference](https://backstage.io/docs/features/software-catalog/references#string-references) to the owner of the entity, e.g. `owner: user:enu43627`. Users and Groups are automatically populated, and can listed in the catalog by filtering by `Kind` of `User` or `Group` respectively.
 
 The owner of an entity is the `group` or `user` that bears ultimate responsibility for the entity, and has the authority and capability to develop and maintain it. They will be the point of contact if something goes wrong, or if features are to be requested. The main purpose of this field is for display purposes in Backstage, so that people looking at catalog items can get an understanding of to whom this entity belongs. It is not to be used by automated processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the entity, but there will always be one ultimate owner.

docs/common/entity-system.md

@@ -1 +1,3 @@
+<!-- markdownlint-disable MD041 -->
+
 An [entity reference](https://backstage.io/docs/features/software-catalog/references#string-references) to the [System](../explanations/system.md) that the entity belongs to, e.g. `developer-portal`. There is no requirement for this System to be created within the same location; Existing Systems can be listed in the catalog by filtering by `Kind` of `System`.

docs/how-tos/link-to-remote-entities.md

@@ -62,7 +62,7 @@ Finally, we will fill out the `spec`. Only the `targets` field is required with
         - ./catalog-info/backend-rest.yaml
     ```
 
-??? example "Example Completed Descriptor"
+!!! example "Example Completed Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/how-tos/publish-a-techdocs-site.md

@@ -45,7 +45,7 @@ We will now run:
 npx @techdocs/cli publish --entity <NAMESPACE/KIND/NAME> --publisher-type awsS3 --storage-name techdocs --awsEndpoint https://s3.echo.stfc.ac.uk --awsS3ForcePathStyle
 ```
 
-??? example "Example GitHub Workflow"
+!!! example "Example GitHub Workflow"
 
     ```yaml
     name: Docs CI
@@ -93,7 +93,7 @@ npx @techdocs/cli publish --entity <NAMESPACE/KIND/NAME> --publisher-type awsS3
             AWS_REGION: ""
     ```
 
-??? example "Example GitLab Workflow"
+!!! example "Example GitLab Workflow"
 
     ```yaml
     image: node:18-bullseye
@@ -132,7 +132,7 @@ npx @techdocs/cli publish --entity <NAMESPACE/KIND/NAME> --publisher-type awsS3
 
 Finally, we will add the `backstage.io/techdocs-ref` annotation to the `metadata.annotations` field of the entity descriptor. This should point to the root directory of the documentation (i.e. the directory containing the `mkdocs.yaml` file).
 
-??? example "Example Entity Descriptor"
+!!! example "Example Entity Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/how-tos/register-a-component.md

@@ -52,7 +52,7 @@ Finally, we will fill out the `spec`. Only the `type` field is required with num
       owner: user:enu43627
     ```
 
-??? example "Example Complete Descriptor"
+!!! example "Example Complete Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/how-tos/register-a-resource.md

@@ -51,7 +51,7 @@ Finally, we will fill out the `spec`. The `type` and `owner` fields are required
       owner: user:enu43627
     ```
 
-??? example "Example Complete Descriptor"
+!!! example "Example Complete Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/how-tos/register-a-static-api.md

@@ -61,7 +61,7 @@ Finally, we will fill out the `API` `spec`. A `type`, a `lifecycle`, an `owner`
 
     It may often be more convenient to link to a generated schema, this can be achieved with use of the `$text` substituion which points to the URL of a schema definiton. For example, a url of the form `https://github.com/DiamondLightSource/<your_repo>/releases/latest/download/<your_schema_file>` can be used to load the contents of the `<your_schema>` artifact from the latest GitHub release.
 
-??? example "Example Completed Descriptor"
+!!! example "Example Completed Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/how-tos/register-a-system.md

@@ -54,7 +54,7 @@ Finally, we will fill out the `spec`. There are no required fields here. However
       owner: user:enu43627
     ```
 
-??? example "Example Completed Descriptor"
+!!! example "Example Completed Descriptor"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1

docs/index.md

@@ -20,4 +20,3 @@ The User Guide contains documentation on how to use the developer portal. This i
 - [**Explanations** :link:](explanations/index.md) provide insight into how the service works and why it works that way.
 
 - [**References** :link:](references/index.md) provide technical reference material including APIs and release notes.
-

docs/tutorials/web-app.md

@@ -92,7 +92,7 @@ spec:
   owner: user:enu43627
 ```
 
-??? example "Complete System Definition"
+!!! example "Complete System Definition"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1
@@ -147,7 +147,7 @@ spec:
     - my-web-app-rest
 ```
 
-??? example "Complete Backend Component Definition"
+!!! example "Complete Backend Component Definition"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1
@@ -210,7 +210,7 @@ spec:
       version: 0.0.1
 ```
 
-??? example "Complete API Definition"
+!!! example "Complete API Definition"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1
@@ -269,7 +269,7 @@ spec:
     - my-web-app-rest
 ```
 
-??? example "Complete Frontend Component Definition"
+!!! example "Complete Frontend Component Definition"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1
@@ -291,7 +291,7 @@ spec:
 
 Once complete we can save and exit, to do so in `nano` press `CTRL` + `X` to exit, `Y` to save and :material-keyboard-return: `Return` to overwrite the opened file.
 
-??? example "Complete Entity Descriptor File"
+!!! example "Complete Entity Descriptor File"
 
     ```yaml
     apiVersion: backstage.io/v1alpha1