Skip to content

Add script + pandoc template to turn README.md into docs site#1419

Draft
Scotsguy wants to merge 3 commits into9001:hovudstraumfrom
Scotsguy:pandoc-docs
Draft

Add script + pandoc template to turn README.md into docs site#1419
Scotsguy wants to merge 3 commits into9001:hovudstraumfrom
Scotsguy:pandoc-docs

Conversation

@Scotsguy
Copy link
Copy Markdown
Contributor

@Scotsguy Scotsguy commented Apr 4, 2026

pandoc is a very versatile tool for converting between document formats. one of the output formats it supports is "chunkedhtml", which consists of multiple html files, one for each top-level heading of the input.

inspired by this tangled blogpost, we can use pandoc and a custom template that moves the table of contents into a sidebar, we can turn the README.md into a quite passable docs site without rewriting everything:

Screen Shot 2026-04-04 at 21 37 31

TODO:

  • mobile support
    • DetailsScreen Shot 2026-04-04 at 21 38 22
    • tangled do the TOC with a popover for a JS-free solution, seems to work well
  • CSS for tables done
  • (maybe a later PR) headings don't have anchor links in the main text, only in the TOC. this needs a lua hook.

needs discussion:

  • I have no idea what I'm doing wrt. CSS, I would appreciate a review
    • in particular, the hack for centering images while also letting them be wider than the text doesn't affect the scroll bar, so you can scroll to the right into nothingness fixed (worked around?)
  • relative links that used to point into the file tree (in particular, docs/) now point into nothingness. I'm not sure if it's a better idea to make these absolute links or also host docs/ or something else
    • perhaps replace the giant README.md with a normal-sized readme and move the current readme into docs/. that way we wouldn't have to worry about the links still working on github.
      • for ctrl+f purposes, tangled also assembles one giant single-page version of their docs.

This PR complies with the DCO; https://developercertificate.org/

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.

1 participant