v4 Milestone

[5e-Cleric]

This discussion will track the progress towards our Version 4, previously tracked in #2879, and in the v4 Milestone.

Introduction

Since this project started, main versions have brought breaking changes to the tool, mainly its rendering engine.

I wasn't here for v2, so i can't speak much about it, but v3 brought mustache syntax for divs and spans, proper column breaks, and more. Made it easy for users to make more complex stuff without the ugly html syntax.

Hopefully, v4 will bring changes equally as important.

Agreed changes

Syntax changes:

ELEMENT	v3 SYNTAX	v4 SYNTAX
underline	<u>underline</u>	_underline_

[5e-Cleric]

Other issues raised that i don't think need to have anything to do with v4, but kept beacuse they have been suggested:

• Typescript rewrite (ew)
• Responsive / Mobile UI
• Two-way interaction between renderer and editor
• Pop out editor + right side editor
• simultaneous editing
• V4 metadata - Initial #4733 (i guess this one is related to rendering)

[Gazook89]

Yeah none of these are breaking changes, so not limited to V4. But releasing them at the same time as v4 would have greater impact.

I agree about typescript: ew.

Popout Editor: I think the splitPane component could be improved generally

• pop out either side
• swap sides
• make it easier to drag the divider from the edge if using touch phone (without accidentally navigating back/forward in browser history)
• click/tap divider bar to center it or move it entirely to one side (rotating between centered, preview only, editor only).

[5e-Cleric]

Gazook, you were he one who raised typescript!

[Gazook89]

I've grown wiser. Or stupider. The point is, I'm dynamic.

[calculuschild]

Proposal: "Vertical Space HTML Hard Breaks"

Summary:
Regardless of Markdown implementation, let "vertical spacing" syntax emit Hard Breaks (<br> instead of <div class='blank'>).

Background:
We tried this before with v3.18.0, but it messed with existing documents just enough that we had to roll it back. This has already been made into an NPM package as well, though it may require adding some tests and general cleanup.

References:

• https://www.reddit.com/r/homebrewery/s/aiZo6Z099q
• https://www.npmjs.com/package/marked-hard-breaks

[dbolack-ab]

I would break out each concept under the ToC foldout into a distinct topic.

Each is its own issue without direct dependencies.

IE:

• Indexes
• ToC/Header Markers
• Changing hard break inserts from : to \\
• Changing the HTML for the Hard Break insert

I would add:

• Glossary builder - Glossaries #4152
• Additional export formats (probably distinct topics each) - EPUB, Mobi, CBZ, CBZ, HTML bundles, etc.
• Brew Variable to CSS property lifting (one method: Add Transfer mechanism for inserting Brew vars into css vars plus HB_pageNumber workaround #4227 )
• Soft/Dynamic page breaks
• brewWright and/or other external PDF (DocRaptor, etc.) generation engine scaffolding
• "homebrewery" brew themes account for "official" brew based themes for automatic pulldown inclusion.
• extended variable processing for walking JSON variables.

[dbolack-ab]

Another addition:

• Theme constants

[5e-Cleric]

Not Agreed upon yet

These are suggestions that have been made but there hasn't been a grumble of acceptance or messages accepting it that i can find.
Longer suggestions are hidden under details elements to make this discussion not incredibly long.

Index & TOC markers

Details

Index Markers (already in #3133)
Basically #label (no space after #) to indicate an entry that should appear in an index, plus some sugar added on to indicate synonyms/parent/child relationships between entries. #index | synonym or similar if I recall.

Which makes me think perhaps we can extend headers in a similar way to guide TOC generation instead of relying upon CSS --excludeTOC tags? Given that indices and table of contents fall into a similar class of "auto-generated structure".

TOC Markers
Some permutation of # Header @ where @ is some symbol or string we devise to indicate that a header should be excluded/included from the Table of Contents.

Another proposal for V4: Change :::: "vertical spacing" to \\, and have it emit
instead of

Already in CommonMark, we have a way to generate
by ending a line with two spaces or a . So you can do something like this:

text
\
\
\
more text
To get a series of breaks. It seems we could just build on that to allow \\ for multiple breaks:

text
\\\
more text
In the same way we already use :::. In other words, we extend the "line break" syntax and potentially remove conflicts with other :-based syntax.

This one would collide with escaping character syntax.

Table of contents syntax change

Details

Table of contents

I think we can move away from using headers in the formatting of the Table of Contents. So instead of this:

{{toc,wide

Contents

• {{ cat}}{{ 3}}

  • {{ dog}}{{ 3}}

}}
we have this:

{{toc,wide

Contents

• {{ cat}}{{ 3}}
  • {{ dog}}{{ 3}}
    }}
    Semantically, a table of contents shouldn't be written as headers itself. Further, it would make the HeaderNav easier, because right now we have special logic to keep the ToC headers from appearing in the HeaderNav.

Edit

We could go further in simplifying the ToC if we didn't care about semantics.....Instead of spans, we could use an html node to separate the link text from the link page number that has a simpler markdown syntax than {{ text}}. Something like italic syntax. This would give us an HTML node that we can apply CSS too but be simpler to read/write:

{{toc,wide

Contents

• cat 3
  • dog 3
    }}

Syntax for easier font-face declaration:

Details

It'd be nice to make font imports easier. So that in the Style Editor, one could do this:

/* [@font "Inter" variable] */

// or

/* [@font "Inter" static 400 100 700 italic bold normal] */
Or similar, and essentially get this:

@font-face {
font-family: 'Inter Variable';
font-style: normal;
font-display: swap;
font-weight: 100 900;
src: url(https://cdn.jsdelivr.net/fontsource/fonts/inter:vf@latest/latin-wght-normal.woff2) format('woff2-variations');
unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
}
This utilizes the CDN for fontsource.org, which is basically Google Fonts (same library, plus some more). It's not google fonts, because Google changes their fonts with updates and are not versioned, whereas fontsource can be (or like above, set with latest). And it doesn't have Google tracking.

Fontsource offers two regular patterns for their URLs, depending on variable or static:

// static
https://cdn.jsdelivr.net/fontsource/fonts/{id}@{version}/{subset}-{weight}-{style}.{extension}

// variable
`https://cdn.jsdelivr.net/fontsource/fonts/{id}:vf@{version}/{subset}-{axes}-{style}.woff2
I would expect this to be something entered in the Style Editor, not the Markdown/Brew editor, so I think it'd be the first foray into processing a new syntax in the CSS document? And to keep it valid CSS, it would be wrapped in a CSS comment syntax, in case someone is taking the CSS portion and trying to use it elsewhere.

Footnote

.footnote class change to .footer

Give classes to the empty nbsp; p elements around column break

<div class="columnWrapper">
  <p>&nbsp;</p>       <!---- here ----> 
  <div class="columnSplit"></div>
  <p>&nbsp;</p>       <!---- here ----> 
</div>