feat: support custom indent sublists BM-1120

[tawera-manaena]

This PR is a sibling of this PR in the basemaps-mkdocs repository.

---

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:

  - Parent
      - Child

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

  - 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, 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

  • 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).

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

• This pull request

  • MkDocs configuration (mkdocs.yml)

    • Updated the mkdocs.yml file of the linz/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:

  # 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:

  # 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:

  - 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

[Wentao-Kuang]

The build-doc deployment seems broken in CI/CD

[tawera-manaena]

The build-doc deployment seems broken in CI/CD

I anticipate that at the moment. The sibling PR will need to be approved first as it updates the basemaps-mkdocs image as required for this PR to pass the checks. Happy to explain any concerns.

Update

The sibling PR has been approved and merged into the basemaps-mkdocs master branch with a new release. The previously failing check now succeeds. 🎉