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

doc: fix improper code blocks parsing for lua_api_deploy by using pymdown-extensions #13847

Merged
merged 1 commit into from Oct 3, 2023

Conversation

corpserot
Copy link
Contributor

@corpserot corpserot commented Sep 25, 2023

This PR replaces the default fenced code blocks extension with a workaround extension, pymdown-extension's superfences. As I don't have experience with deploying on github pages, i was only able to verify this locally and see that the codeblock for minetest.features is rendered as expected.

Notes

Minetest uses mkdocs to build documentation, which in turn uses python-markdown which then notes:

This is not a CommonMark implementation; nor is it trying to be! Python-Markdown was developed long before the CommonMark specification was released and has always (mostly) followed the syntax rules and behavior of the original reference implementation. No accommodations have been made to address the changes which CommonMark has suggested. It is recommended that you look elsewhere if you want an implementation which follows the CommonMark specification.

With this in mind, the project does not implement fenced code blocks like ```lua .. ``` used currently in doc/. This feature is brought in by mkdocs using fenced_code_blocks extension which doesn't support nesting it inside container blocks (i.e. lists) or even having any indentation to the whole block. furthermore, changes to doc/ from someone expecting a full commonmark implementation may result in improper formatting.

@rubenwardy rubenwardy added the Bugfix 🐛 PRs that fix a bug label Sep 25, 2023
@rollerozxa
Copy link
Member

Looks good, works well and fixes the currently ugly or broken codeblocks in the rendered documentation. Left is with this PR, right is on master (https://api.minetest.net/minetest-namespace-reference/):

image

@p-ouellette
Copy link
Contributor

If full CommonMark (or GFM) support is wanted, you could switch from MkDocs to Sphinx + MyST-Parser: https://www.sphinx-doc.org/en/master/usage/markdown.html

Copy link
Member

@grorp grorp left a comment

Choose a reason for hiding this comment

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

Works. Thank you.

@nerzhul nerzhul merged commit 5a56972 into minetest:master Oct 3, 2023
Zughy pushed a commit to Zughy/minetest that referenced this pull request Oct 8, 2023
kawogi pushed a commit to kawogi/minetest that referenced this pull request Dec 19, 2023
cosin15 pushed a commit to cosin15/minetest that referenced this pull request Feb 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants