dhall-lang / dhall-haskell

Maintainable configuration files
https://dhall-lang.org/
BSD 3-Clause "New" or "Revised" License
912 stars 213 forks source link

Render Markdown files as HTML #2579

Closed kukimik closed 5 months ago

kukimik commented 6 months ago

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 commented 5 months ago

@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 commented 5 months ago

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

kukimik commented 5 months ago

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