Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize whitespace and tabs in source for indentation-sensitive markup features #755

Open
2 tasks
felker opened this issue Feb 26, 2025 · 0 comments
Open
2 tasks
Labels
maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) mkdocs enhancement Changes to mkdocs features, mkdocs-material theme, custom theme overrides, etc. style subjective design choices, language conventions, how and when to use mkdocs & theme features

Comments

@felker
Copy link
Member

felker commented Feb 26, 2025

A note from #640, specifically https://github.com/argonne-lcf/user-guides/pull/640/files#r1919104321

Admonitions can be very picky about indentation in order to render correctly:

The content of the block follows on the next line, indented by four spaces:

E.g. when using !!! note the block should begin on the next line with content with the first letter under the n (or later?)

A single tab character seems to still work, e.g. in:

!!! warning
If you want to `ssh` or `scp` to one of your assigned compute nodes you will need to make sure your `$HOME` directory and your `$HOME/.ssh` directory permissions are both set to `700`.

(and throughout that .md, it seems like a mix of whitespace+tabs, 6 whitespaces, etc. indentation for Admonitions all seem to render correctly in mkdocs-material...)

By default, GitHub renders tabs in Markdown rich previews as 8 spaces, so it can be hard to spot errors. And changing a GitHub user's default "number of spaces a tab is equal to when rendering code" from 8 to 4 via https://github.com/settings/appearance is not reflected everywhere, e.g. the above permalink snippet in this comment.
Image

Tab characters would be better replaced by 4 whitespaces. Our AI proofreader seems to agree; it replaced the tab character below with 4 spaces in 8a62194
Image

  • replace all tab characters and prevent them from being introduced in future commits?
  • Or, this is another reason to move to the new API (Upgrade to pymdownx's new Blocks API  #609), where Admonitions and Blocks generally are not whitespace-sensitive.

Related to #330 and the potential benefit from having automatically-enforced style rules.

@felker felker added mkdocs enhancement Changes to mkdocs features, mkdocs-material theme, custom theme overrides, etc. maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) style subjective design choices, language conventions, how and when to use mkdocs & theme features labels Mar 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
maintenance Preserving quality source code and tools for docs authors (via GitHub Actions, CLI utilities, etc.) mkdocs enhancement Changes to mkdocs features, mkdocs-material theme, custom theme overrides, etc. style subjective design choices, language conventions, how and when to use mkdocs & theme features
Projects
None yet
Development

No branches or pull requests

1 participant