From bc334d4f0c36425c3f9d3bd33b1cd338f26c0690 Mon Sep 17 00:00:00 2001
From: Tawera Manaena <TManaena@linz.govt.nz>
Date: Fri, 15 Nov 2024 09:28:04 +1300
Subject: [PATCH] feat: support custom indent sublists BM-1120 (#3371)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR is a sibling of [this PR][pr] in the **basemaps-mkdocs**
repository.

[pr]: https://github.com/linz/basemaps-mkdocs/pull/8

---

### Problem

When formatting markdown (`.md`) files in Visual Studio Code, sublists
are lost due to LINZ's formatting rules around how many spaces prescribe
a _tab_.

- Currently, MkDocs requires sublist items to be indented 4 spaces
relative to the parent. Like so:

  ```md
  - Parent
      - Child
  ```

- However, LINZ's Prettier formatting rules
([.prettierrc.cjs][prettier]) trims such occurrences down to 2 spaces:

  ```md
  - Parent
    - Child
  ```

After the formatting, MkDocs interprets the `Child` sublist item as a
member of the parent list. Effectively, the sublist is lost.

### Solution

I have identified a markdown extension called
[mdx_truly_sane_lists][mdx], which can solve the problem. The extension
allows us to override the number of spaces required for MkDocs to
preserve a sublist item from 4 spaces to 2 spaces, inline with LINZ's
Prettier formatting rules.

### Modifications

- #### [Sibling pull request][pr]

  - #### Dockerfile

- Added an install command for the `mdx_truly_sane_lists` markdown
extension.
- Updated the MkDocs base image to the latest version
([9.5.44](mkdocs)).

> Not required for the extension to work, just a convenient time to
update the image.

- #### This pull request

  - #### MkDocs configuration ([mkdocs.yml][yml])

- Updated the [mkdocs.yml][yml] file of the [linz/basemaps][basemaps]
repo so that MkDocs uses the extension.

### Verification


- #### Building the Docker image

I used the following command to build a Docker image with which I could
test my modifications:

  ```bash
  # from the root of the `basemaps-mkdocs` repo
  docker build --tag basemaps-mkdocs-test .
  ```

- #### Serving MkDocs locally

I then used the following command to serve MkDocs locally using the
Docker image:

  ```bash
  # from the root of the `basemaps` repo
docker run --rm -v $PWD:/docs -p 8000:8000 basemaps-mkdocs-test serve -a
0.0.0.0:8000
  ```

- #### Testing sublist indent

  For the given markdown [snippet][snippet]:

  ```md
  - build the **basemaps** packages
  - configure and run the **basemaps/server** package:
    - using LINZ's imagery
    - using your own imagery
  ```
  MkDocs correctly preserves the sublist items! 🎉
  | Before | After |
  | - | - |
  | ![][before] | ![][after] |

[jira]: https://toitutewhenua.atlassian.net/browse/BM-1120
[prettier]:
https://github.com/linz/style-js/blob/437f754e17eca905a880606219c832e8fc9d5f9c/.prettierrc.cjs
[mdx]: https://github.com/radude/mdx_truly_sane_lists
[mkdocs]:
https://github.com/squidfunk/mkdocs-material/pkgs/container/mkdocs-material/300822759?tag=9.5.44
[yml]:
https://github.com/linz/basemaps/blob/385971dc23c0b1cd9c354c5028d47d01ab5ae584/mkdocs.yml
[basemaps]: https://github.com/linz/basemaps
[snippet]:
https://github.com/linz/basemaps/blob/385971dc23c0b1cd9c354c5028d47d01ab5ae584/docs/developer-guide/run-basemaps-locally.md
[before]:
https://github.com/user-attachments/assets/0ddbbbaa-9b1a-49df-bf54-74c2d7357d0d
[after]:
https://github.com/user-attachments/assets/301f7ca5-80e5-4bf9-97c2-4841a0bec68b
---
 docs/developer-guide/run-basemaps-locally.md | 8 ++++----
 mkdocs.yml                                   | 6 ++++++
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/developer-guide/run-basemaps-locally.md b/docs/developer-guide/run-basemaps-locally.md
index 3d3a3cbea..42bacfc9d 100644
--- a/docs/developer-guide/run-basemaps-locally.md
+++ b/docs/developer-guide/run-basemaps-locally.md
@@ -4,8 +4,8 @@ This guide shows you how to set up and run a local instance of the **basemaps**
 
 - build the **basemaps** packages
 - configure and run the **basemaps/server** package:
-    - using LINZ's imagery
-    - using your own imagery
+  - using LINZ's imagery
+  - using your own imagery
 
 !!! note
 
@@ -56,7 +56,7 @@ Clone the [**linz/basemaps**][bm_repo] repository to your machine.
 !!! abstract "Path"
 
     This guide uses variables as shorthand to reference key directories and files. On your machine, consider the following path:
-    
+
     === "`BM_REPO`"
 
         The path to the **basemaps** repository folder on your machine.
@@ -102,4 +102,4 @@ There are two main ways you can configure and run the **basemaps/server** packag
 [bm_repo]: https://github.com/linz/basemaps
 [configuration]: https://github.com/linz/basemaps/blob/master/docs/configuration.md
 [contributing]: https://github.com/linz/basemaps/blob/master/CONTRIBUTING.md
-[stac]: https://github.com/radiantearth/stac-spec/blob/master/overview.md
\ No newline at end of file
+[stac]: https://github.com/radiantearth/stac-spec/blob/master/overview.md
diff --git a/mkdocs.yml b/mkdocs.yml
index ee31016c9..c345947a6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -74,6 +74,12 @@ markdown_extensions:
   - pymdownx.tabbed:
       alternate_style: true
 
+  # Overrides indent required for sublist items
+  #
+  # https://github.com/radude/mdx_truly_sane_lists
+  - mdx_truly_sane_lists:
+      nested_indent: 2
+
 # Load google analytics from the $GOOGLE_ANALYTICS environment var
 extra:
   analytics: