Skip to content

Conversation

@gulshan-123
Copy link

Solves #6610, Hi I am a new contributor to grass! Excited to contribute more...

This PR enables proper rendering of mathematical expressions in the GRASS MkDocs documentation.
Some manual pages such as r.runoff contain LaTeX formulas, but these were previously shown as raw $...$ text. This update integrates MathJax and the required Markdown extension so that equations render correctly both inline and in block form.


Testing

## Math test

Inline: $x^2 + y^2 = z^2$.

Block:

$$
E = mc^2
$$

Its Output:
image


Notes from local build experience

While testing this change locally, I found it non-obvious how to build and preview the documentation.
At first, addon manual pages like r.runoff were missing, and changes in index.md had no visible effect.
Eventually I realized that MkDocs serves content from the generated directory:

dist.x86_64-pc-linux-gnu/docs/mkdocs/

and not directly from files under man/.
After updating the correct mkdocs.yml and the generated source/index.md inside the dist folder, MathJax worked as expected.
The final changes in this PR are applied to man/mkdocs/mkdocs.yml

@github-actions github-actions bot added the docs label Dec 6, 2025
@gulshan-123 gulshan-123 changed the title Enable MathJax rendering for equations in MkDocs documentation doc: Enable MathJax rendering for equations in MkDocs documentation Dec 6, 2025
@gulshan-123
Copy link
Author

I have also tested the r.runoff file by pasting it to index.md just for local testing.

Results is as required:
Screenshot from 2025-12-06 12-01-04

Screenshot from 2025-12-06 12-01-10 Screenshot from 2025-12-06 12-01-18 Screenshot from 2025-12-06 12-01-25

@petrasovaa
Copy link
Contributor

Thanks! There is another PR (#6610) opened for this, but the author didn't follow up on a question we had there that applies to your PR as well

Why is the polyfill needed and have you tried using mathjax 4.0?

@gulshan-123
Copy link
Author

gulshan-123 commented Dec 8, 2025

Thank you for the review, I have now changed to v4.

Why is the polyfill needed and have you tried using mathjax 4.0?

polyfill was required to be used on some older browser for v3.
But, now I am using version 4, so polyfill is not required and not recommended.

Quoting from docs:
Browser Compatibility

MathJax supports all modern browsers (Chrome, Safari, Firefox, Edge), and most mobile browsers. We no longer test MathJax with IE11, so you should not expect it to work with any version of Internet Explorer. We used to recommend loading the polyfill library in order to help MathJax work with older browsers, but that is not necessary for modern browsers, and we no longer recommend it.

EDIT: I have tested the doc build, The result is the same, thus we should keep v4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants