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

Render Markdown files as HTML #2579

Merged
merged 2 commits into from
Apr 7, 2024
Merged

Conversation

kukimik
Copy link
Collaborator

@kukimik kukimik commented Apr 3, 2024

This PR introduces HTML rendering of Markdown files, as announced in #2565. The main usecase is rendering README.md files accompanying a package.

If a file has the .md extension and can be parsed by the MMark parser, we display both the HTML output generated by MMark, and the Markdown sources, which are hidden by default using a <details> tag. If a problem occurs in the parsing phase, we treat the file as plain text and display a warning.

One issue that I am aware of is handling of local (non-external) links. For example in the Prelude's README.md we have a link pointing to ./Natural/fold. In the generated documentation this will stil point to ./Natural/fold, but there is no such file in the docs: we are missing the .html extension. (And for links to folders we should add a trailing /index.html.) A "full" solution of this could be rather tricky, as it should involve handling of symlinks etc., and would probably need IO and some restructuring of the code. I think a simple solution that works in most real-life scenarios can be implemented using a MMark extension, a helper function similar to shake's NormaliseEx and the list of rendered files. However, this would still require some work, and I believe the present changes already improve the dhall-docs tool a little bit, so I'd rather take care of this in a separate PR. (Moreover, rendering of comments in .dhall files has the same issue, so it could be fixed in both places at once.)

@kukimik
Copy link
Collaborator Author

kukimik commented Apr 5, 2024

@Gabriella439 There's a problem with the hydra build (a cached out-of-disk-space failure), it affects all new PRs. No rush, I'm just pinging in case you missed it.

@Gabriella439
Copy link
Collaborator

I fixed the disk issues, although the dhall-docs build still has one test failure remaining

@kukimik
Copy link
Collaborator Author

kukimik commented Apr 7, 2024

Thanks! I forgot to add the new test files as Extra-Source-Files in dhall-docs.cabal. Fixed.

@Gabriella439 Gabriella439 merged commit 9075b91 into dhall-lang:main Apr 7, 2024
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants