New Parser/Renderer

[calculuschild]

Future updates and fixes for current bugs is becoming more difficult due to the current structure of the Markdown->HTML->Render pipeline. This is partly due to unforseen consequences of early design choices, layers of patches and band-aids, and users with custom styling and HTML. We propose creating a new "V2" pipeline which will become the new default, leaving behind the current implementation as a "legacy" option so as to preserve older brews, but limiting further updates on that path. We have learned a lot as the Homebrewery has grown and become more popular, and it is time to put it to use in a new, better version.

This issue will collect the sub-tasks and related issues.

Note: @stolksdorf did a lot of almost all of this work already, and even totally cleaned up and organized everything. The NewRenderer branch is a goldmine. Some of it might not be compatible with the current codebase, but I really like what he's done.

Tasks

Create new render pipeline, "V3"

• Collect legacy code into separate "legacy renderer" pipeline
• Add "Homebrewery Version" tag to brews ("legacy" or "V3")
• Switch between render pipelines based on Version tag
• Update Markdown version for new pipeline (Editor highlighting for Markdown italics do not match rendered brew #852)

Restructure PHB Styling

• Implement CSS Div classes in Markdown (Markdown - adding classname to elements #403)
  • Define formatting (mustache-like vs Pandoc fenced divs, etc.)
  • Add CodeMirror highlighting to the mustache syntax
• Update styling and rebuild Snippets to use mustache syntax instead of janky Markdown combinations
  • Standard paragraph text
  • Headers
    • H1
    • H2
    • H3
    • H4
    • H5
  • Drop caps (fancy first letter)
  • Monster stat blocks Statblock Format Improvement #509
    • Standard
    • Wide
    • Border-less
  • Tables
    • Standard table
    • Wide table
    • Split table
    • Class table
    • Half class table
  • Note box
  • Descriptive box
  • Spell
  • Spell list
  • Class feature
  • Cover page
  • Vertical spacing
  • Column break
  • Page break
  • Wide block
  • Image
  • Background image
  • Page number
  • Auto-incrementing page number
  • Link to page
  • Table of Contents Full-page Table-of-Contents #304
  • Tweak drop cap
• Update to latest version of Marked.js for more accurate parsing (and fewer weird bugs)
• Use /column instead of code fences for column breaks
• /column and /page must occur alone at beginning of a line to prevent accidental page breaks (Only page break when \page occurs alone at beginning of a line #1147)

Other issues fixed by this rework

[Gazook89]

I saw mention somewhere that the new version won't allow direct html, and for awhile i've been wondering if that is 100% true, or if it just won't allow some html? Can you confirm either way, and what html tags might remain available (or become not available)?

[calculuschild]

We will still allow HTML. I think there are way too many people out there who love the Homebrewery precisely because of how customizable it is (including me).

However, we will no longer "support" raw HTML. Meaning, if something breaks because you have bad HTML, we aren't going prioritize pushing out code fixes to make sure your custom thing works (and if an update breaks your custom thing, we warned you).

We have gone a long way towards preventing random crashes, etc. from custom HTML, but at some point it's beyond the scope of the Homebrewery's goals. Plus, if we can encourage and supply everything 95% of people need just with Markdown, I think that lowers the barrier to entry for a lot of people who don't necessarily know the difference between HTML and Markdown or any computer language at all.

[Gazook89]

Is this 2017 post by Stolksdorf basically the foundation of the new renderer? The curly braces "divs" and such? Just happened across it and thought it is a well reasoned argument. Particularly the concern about moving from "photoshop expertise to coding expertise" and the issues around that.

Maintaining divs was my biggest concern, and the "blocks" will do that. If this is the route forward, that is good to know because I will start to think about writing my guides (and possible snippets) with that in mind.

[calculuschild]

Yep, that's where it comes from. He even posted 90% of the work already here on Github, but just didn't quite get the final bits finished to publish it. There are a lot of good reasons to make the changes.

Now, my understanding is he wanted to fully remove any HTML capabilities, which we could do, but I don't know if such a drastic restriction is for the best. There are a few cases such as with <br> or even custom tweaks in tables that would no longer be possible. But maybe this can be a part of the "beta" phase as people opt in and we can see how critical it is.

What we might start with, though, is removing the janky code that renders markdown inside of other HTML. Normally, <div> **bold** </div> would not recognize the markdown inside the Div, but we made special code to allow that (and it has weird unexpected consequences unfortunately). So if you want a block of custom HTML, it would require HTML only for everything inside as well.

[Gazook89]

I see that "class table" is ticked as complete on the above list-- i just inserted a class table in v3 and it still comes up using divs rather than moustache syntax. just fyi.

[Gazook89]

ugh, sorry, ignore me....i think i looked at monster stat blocks by mistake.

[Gazook89]

Close this bad boy out? Cover Page snippet never got done, but let's lump that together with a new issue regarding "Page Layout" snippets as mentioned in #781.

Leaving to @calculuschild for the cathartic release.

[calculuschild]

...yeah... I guess... It's done isn't it?

Ooo-weee.

Yep, let's move cover page to the new issue and close this out.