Skip to content

Conversation

@mschoettle
Copy link
Contributor

@mschoettle mschoettle commented Dec 5, 2025

Description

Formats all (almost) Markdown files with mdformat and the mdformat-mkdocs plugin.

Adds mdformat --check in a step to the docs CI workflow.

Related Issue

n/a

Motivation and Context

As discussed in:

How Has This Been Tested?

Locally and via the the new CI step.

Screenshots (if appropriate):

To consider

  1. I added the configuation file (.mdformat.toml) because it makes it easier to run mdformat in various places with the same config.

    I wanted to add mdformat to the Dockerfile, unfortunately, --exclude requires Python 3.13and themkdocs-materialimage still uses Python 3.11. It could be changed to though if you think that would be a better experience as well (either by usinguvto runmdformat` or changing the base image).
    It would then also make it possible to add it to the Makefile.

  2. I enabled --compact-tables to avoid sweeping formatting changes in the tables but we could remove that.

  3. It is also possible to format code blocks. I tried it out with the mkdocs-beautysh for shell scripts and mkdocs-config for TOML, JSON, and YAML files. Shell scripts didn't fully "work" due to the comments in multiline arguments. It would require a trailing slash at the end of those comments to avoid indentation changes in the next line. Via beautysh it helped find two missing trailing slashes :)

@semanticdiff-com
Copy link

semanticdiff-com bot commented Dec 5, 2025

Review changes with  SemanticDiff

Changed Files
File Status
  .github/workflows/devel.project.docs.yml  0% smaller
  .mdformat.toml Unsupported file format
  README.md Unsupported file format
  SECURITY.md Unsupported file format
  docs/CODE_STYLE.md Unsupported file format
  docs/COMMITS.md Unsupported file format
  docs/content/building-from-source.md Unsupported file format
  docs/content/configuration/command-line-arguments.md Unsupported file format
  docs/content/configuration/config-file.md Unsupported file format
  docs/content/configuration/environment-variables.md Unsupported file format
  docs/content/download-and-install.template.md Unsupported file format
  docs/content/features/basic-authentication.md Unsupported file format
  docs/content/features/blocking-threads.md Unsupported file format
  docs/content/features/cache-control-headers.md Unsupported file format
  docs/content/features/compression-static.md Unsupported file format
  docs/content/features/cors.md Unsupported file format
  docs/content/features/custom-http-headers.md Unsupported file format
  docs/content/features/directory-listing.md Unsupported file format
  docs/content/features/docker.md Unsupported file format
  docs/content/features/error-pages.md Unsupported file format
  docs/content/features/file-descriptor-socket-passing.md Unsupported file format
  docs/content/features/graceful-shutdown.md Unsupported file format
  docs/content/features/health-endpoint.md Unsupported file format
  docs/content/features/http-https-redirect.md Unsupported file format
  docs/content/features/http-methods.md Unsupported file format
  docs/content/features/http1.md Unsupported file format
  docs/content/features/http2-tls.md Unsupported file format
  docs/content/features/ignore-files.md Unsupported file format
  docs/content/features/logging.md Unsupported file format
  docs/content/features/maintenance-mode.md Unsupported file format
  docs/content/features/man-pages-completions.md Unsupported file format
  docs/content/features/markdown-content-negotiation.md Unsupported file format
  docs/content/features/multiple-index-files.md Unsupported file format
  docs/content/features/security-headers.md Unsupported file format
  docs/content/features/url-redirects.md Unsupported file format
  docs/content/features/url-rewrites.md Unsupported file format
  docs/content/features/virtual-hosting.md Unsupported file format
  docs/content/features/webassembly.md Unsupported file format
  docs/content/features/windows-service.md Unsupported file format
  docs/content/features/worker-threads.md Unsupported file format
  docs/content/getting-started.md Unsupported file format
  docs/content/index.md Unsupported file format
  docs/content/migration.md Unsupported file format
  docs/content/platforms-architectures.md Unsupported file format

@mschoettle mschoettle changed the title docs: format documentation with mdformat chore: format documentation with mdformat Dec 5, 2025
@mschoettle mschoettle marked this pull request as ready for review December 5, 2025 18:49
@mschoettle mschoettle changed the title chore: format documentation with mdformat chore: format Markdown files with mdformat Dec 5, 2025
@mschoettle
Copy link
Contributor Author

Ready! :)

See the "To consider" section for some things to discuss/consider.

@joseluisq joseluisq changed the title chore: format Markdown files with mdformat Format Markdown files with mdformat Dec 6, 2025
@joseluisq
Copy link
Collaborator

  1. I added the configuation file (.mdformat.toml) because it makes it easier to run mdformat in various places with the same config.

It is fine for now. I thought mdformat supports a config file argument to move it to .github/workflows/config/ but it doesn't.

I wanted to add mdformat to the Dockerfile, unfortunately, --exclude requires Python 3.13and themkdocs-materialimage still uses Python 3.11. It could be changed to though if you think that would be a better experience as well (either by usinguvto runmdformat` or changing the base image).
It would then also make it possible to add it to the Makefile.

We could improve Dockerfile and build mkdocs-material ourselves later, feel free.

  1. I enabled --compact-tables to avoid sweeping formatting changes in the tables but we could remove that.
  2. It is also possible to format code blocks. I tried it out with the mkdocs-beautysh for shell scripts and mkdocs-config for TOML, JSON, and YAML files. Shell scripts didn't fully "work" due to the comments in multiline arguments. It would require a trailing slash at the end of those comments to avoid indentation changes in the next line. Via beautysh it helped find two missing trailing slashes :)

It looks fine to me for now.

Copy link
Collaborator

@joseluisq joseluisq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@joseluisq joseluisq merged commit dd43d06 into static-web-server:master Dec 7, 2025
1 check passed
@joseluisq joseluisq added this to the v2.40.1 milestone Dec 8, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Related to CI/CD enhancement New feature or request v2 v2 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants