Peeragogy: master copy, and formatting Org vs Markdown

Continuing the discussion from Peeragogy dev (December 2020):

So, this is the master copy: (v3)

This is the experimental Org Mode setup that will replace it:

Yes, Github renders Org, e.g.,

But the plan is to move to Firn for rendering, e.g.,

Firn can be set up as a one-for-one replacement of Github Pages/Jekyll, but I’d actually like to go one step further and remove the dependency on Github entirely, moving hosting to a free software solution.

So, in Org it’s possible to define custom blocks:

This means for example if we want to use the Tufte margin, we could add

This is a "mini-Handbook" introducing Org mode:

and that will then be formatted (subject to writing the correct instructions) correctly in both HTML and PDF downstream formats. It would be possible to hack this sort of thing into Markdown, I’d say, but it’s well supported in Org. More semantics can be added as well.

(I’m glossing over the fact that Firn and Org Mode itself have separate rendering strategies; this will all be sorted out eventually!)

1 Like

Thanks, makes sense. Just Markdown doesn’t seem to be a dependency on GitHub to me, as you’re already writing it in CodiMD/HackMD or any other editor as well, and Jekyll can be set up and run as a standalone processor, likely the same way with Firn. Not to mention pandoc apart from its own bag of problems, which has been used in the Peeragogy stack too. Essentially saying that to me, conversion between these two formats doesn’t necessarily add much (except Org-Mode for those who have/use it). Primitive custom plain-text formats (consider them more as a writing “interface”/convention than a text/data format, because lack of semantic bootstrapping). Wikitext however is different, as it targets server-side template renderers with their own custom syntax, which is a pain client-side to reinvent/replicate, no universal/standardized standalone/separate processor/converter apart from what happens to be supported inside/built-in pandoc.

From the PHv4 perspective, the main thing it adds is the special blocks that I mentioned; and, yes, it’s otherwise similar to Markdown. Still, even if someone added similar special blocks to Markdown, I would personally prefer Org Mode because it does have a bunch of other tools/facilities added on to it (in Emacs), and I know these well and can teach them to others. But, Emacs is not a strict dependency for working with the format either.

1 Like

Guess I just tend to get uncomfortable of adding all sorts of syntax hacks to custom plain-text formats, reducing their main point of simplicity, attempting to add more semantics to do more complex stuff with them, which instead could be an inherent semantic format or its own DSL (domain-specific language) to begin with, also integrated into the UI, editors, system, EditSpecs. In lack of the latter nor building one, these formats plus converting it to something more useful/processable (avoiding the need to roll one’s own custom parser every time) works fine, skipping right to the more structured data, leaving it to others to mess with the authoring :slight_smile: As nothing else, better is around or available or on the way, that’s probably as good as it gets.