compare some tools and formats

[milahu]

the readme is missing infos on tooling and formats

this is just a quick braindump, sorry that its not (yet) a PR

my use case:

im in the process of migrating my book from html to markdown

my "wanted specs":

• the source format must be compatible with github/gitlab/gitea blob api, so all of the content is accessible
  • images must work. this is not the case with asciidoc and org-mode. workaround: symlink the global images folder to every content folder
  • tables must work. i use html tables for formatting (oldschool, but "just works")
    • currently i have implemented tables as markdown lists and css grid, but this is ugly in the github/gitlab/gitea blob api, so back to html table
• i want to store annotations in the source (tight coupling)
  • currently i do this with <details> elements in markdown, because they work in github blob api, and because they are better than markdown footnotes: <details> elements can contain arbitrary markdown or html content, while markdown footnotes can only contain markdown
• must be friendly to new contributors
  • everybody knows markdown and html
  • asciidoc and org-mode are more "niche" formats
• ideally the tooling should have "incremental compilation". in the context of Static Site Generators (SSG) this feature is known as Incremental Static Generation (ISG) or Incremental Static Regeneration (ISR)
• avoid commercial services like gitbook or leanpub

i collected some notes on tools, toolchains, source formats in

• https://github.com/milahu/alchi/tree/master/src/whoaremyfriends/markdown#readme
• https://github.com/milahu/alchi/blob/master/src/doc/todo.md

related

• nixos rfc 72 - migrating docs from docbook to markdown

tools: focus on browser-based tools, as these are most portable

• https://github.com/iilab/contentascode/issues/5
• https://github.com/ProseMirror/prosemirror
  • https://github.com/fiduswriter/fiduswriter
  • https://github.com/ueberdosis/tiptap wrapper for prosemirror
• https://github.com/linkeddata/dokieli based on html
• https://github.com/overleaf/overleaf based on latex
• https://github.com/prose/prose based on github, source code editor, file manager
  • waiting for prosemirror integration https://github.com/prose/prose/issues/935
• https://github.com/sofish/pen based on markdown, inplace editor (no page reload)
• https://github.com/facebook/draft-js - a React framework for building text editors
• https://github.com/GitbookIO/repofs - manipulate Git repositories on GitHub
• lenses (bidirectional transformers) (two way binding)
  • https://github.com/showdownjs/showdown - bidirectional transformer (lens) between markdown and html
  • https://github.com/gcanti/monocle-ts