Design HTML-generating companion tool

[benknoble]

I think I could write a program to turn the wiki into a HTML site or something similar. Markdown processing is easy, and source-code can be wrapped in pres.

Challenges:

• every "word" is a potential hyperlink via vim's gf--the right ones need to be resolved to documents and turned into hyperlinks in addition to standard markdown links []() and [][]
• syntax-highlight for code files has to be done based on what vim thinks the filetype is, which could be very slow if we invoke vim once for each file--even doing it once in a batch and building (and outputting) a dictionary of files->types could be slower than we want. This assumes I do not want to re-implement vim's filetype mechanism nor do I want to guess--I want to use whatever the user is used from their vim. But for github actions this may not even be feasible, as everyone has their own vim? This needs some design thought.
• filetype detection is even hairier: I do need to be able to treat markdown (and possibly other markup formats)! Actually, this has to come before syntax-highlighting... I need to be able to leave HTML alone, for example, and possibly (but not always!) JS & CSS... actually, the not always applies to any document. So--do I wrap everything in <pre> with links as a POC? One other option is to include a config that maps "file patterns" to "processors," such as *.md -> md2html, static/* -> noproc, or *.my-ft -> shell('my command')... Alternately, perhaps I could take the filetype mechanism code from ripgrep, and only support processing markdown to HTML as a PoC? Not processing certain files is still an issue, so said filetype mechanism may need adapting into the "processors" as before.

Goals:

• fast
• accessible out of the box (readable, navigable, etc.)

Extensions:

• custom styling with CSS (maybe even JS?)
• syntax highlighting for code (could be achieved by allowing ^); see challenges--this may work better for mardown code than regular files
• GH action or similar to deploy to pages on-push
• support for other markup formats (??)
• searchability (? unclear--may be a stretch or even a non-goal)
• link-graphs à la foam
• back-link support à la foam

Non-goals:

• full templating system
• custom pages (that's what a wiki entry is for!)

[benknoble]

Design thoughts:

Compiling the wiki (and thus running the tool) would probably be faster if I didn't have to find all possible links and create them (fortunately, <a> works in <pre>). This would probably require a custom JS mouse-click handler to try to find the documents, along with an index of documents—ultimately, I think this creates a poor user experience in the name of making it easier for the tool author (me). Someone smart once told me that we, as authors of code, should do the hard work so someone else doesn't have to.

To that end, I would much prefer a design that creates proper links and well-formed HTML—it is more accessible, more standard, and less surprising. I would consider a trade-off in ease of development acceptable towards this goal; moreover, I would be willing to sacrifice some portion of a performance goal in service of a better user experience, though generation speed is still a priority.