feat: support custom indent sublists BM-1120

tawera-manaena commented 2 weeks ago

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 commented 2 weeks ago

The build-doc deployment seems broken in CI/CD

tawera-manaena commented 2 weeks ago

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. 🎉

linz / basemaps