Version 4

[Gazook89]

Opening this discussion to collect ideas in a 'next big version'. There are other discussion threads that focus on more specific aspects of Homebrewery, which I'll link to, but for things that don't have or need their own thing, here we go:

a. Typescript
b. Responsive/Mobile UI (and codemirror 6?)
c. Two-way interaction between renderer and editor (d3.js?)

[5e-Cleric]

AFAIK, CSS layers and brew themes are coming with v4, aren't they?

I'll add to this the idea for the editor modes(pop out editor, or being able to change it to the right of the brew) as it is related to the responsive design. #2780

And if we can, Less and Sass support would be nice to have too, as well as CSS Folding. #2793

[calculuschild]

Themes are intended for v3. Just waiting for bits of cleanup and getting links to custom themes working.

[dbolack-ab]

a. Typescript

Like a full refactor?

b. Responsive/Mobile UI (and codemirror 6?)

Do people do this? try to author on phones or is there something I don't understand?

[calculuschild]

a) I'm actually pretty uneasy about Typescript. Every time i have used it, it adds so much bloat and boilerplate that any stability gained from typing is overwhelmed by illegibility. I would vote no on this.

b) Yeah... I am always surprised but people do try to edit on mobile with some frequency.

[ericscheid]

d) simultaneous editing by multiple authors

[5e-Cleric]

This i've wanted for sooo long, i tend to do my best worldbuilding when i have someone to bounce crazy ideas off.

[5e-Cleric]

e) spellcheck.
AFAIK, you can't use browser's spelling features in an element that is not editable(exc. using duplication of elements).
But we could add a js library for spellchecking
it could even be a toggle spellcheck, if it takes too much memory.

F) snippet preview?

G) FontAwesome icon picker Done

H) All selectable fonts as snippet to add Done

I) OUR OWN PDF RENDERING, i want bookmarks

J) adding comments as if html comments didn't exist

K)BLEEDING

[calculuschild]

I think F, G, and H could be part of V3 if we want. H would actually be really easy and already kind of exists in the Table -> Rune Table snippet.

So yes I agree these would all be nice. But if they would work with V3 in a way that doesn't break anything, we don't have to wait to implement them. V4 would be more for changes that would break V3 (i.e., bleeding would require a lot of redesign of the CSS that would break existing documents, etc).

[dbolack-ab]

I have been beating my head on the PDF thing for a while. I've gotten close - but it honestly looks like it may require a proper markdown to PDF tool.

I'm still trying to get around that.

[ericscheid]

For adding comments to brews I simply use html comments.

<!-- this is a comment -→

There's even a keyboard shortcut for it, and it is easy to select whole brew paragraphs (etc) and then comment them out.

(It does mean it still shows in the rendered html source. I'm OK with that.)

[ericscheid]

Here is my // comment // that is inline

In javascript, everything following the // is a comment. Not just the bit between the pair of //.

If you want an inline comment, it would be like this.

Here is my /* comment */ that is inline

So .. that's two forms of markup for comments.

[Gazook89]

Yeah, that's why i said "semi-javascript". I just like repeating a single character twice rather than complicating it.

However, I very truly do not have a horse in this race. HTML comments seem fine to me. They are visually distinctive from other text (which to me is a bonus for comments), and the others reasons i mentioned.

[5e-Cleric]

i just hate the fact that to comment something i need 5 keystrokes (< Shift+1 - -) for

And before anyone says why don't you use the shortcut, it is not possible with my keyboard, i need shift for outputting /

[dbolack-ab]

It has been discovered recently that:

marked provides <? ?> for comments
marked-smartypants provides <! which can run unenclosed until the end of a text block.

[5e-Cleric]

must point out, some of these produce empty p elements with the comments inside, instead of just the comment.

[5e-Cleric]

As talked about in Gitter today, we might want to add/change writing syntax for some things, like adding underline syntax:

_this text would be underlined_ as syntax
and the shortcut could be Ctrl + u
in the html as <u>this text would be underlined</u>

also italics could use <i> if it doesnt already, and bold should probably use <b>, since we don't care for readers anyway.

• Highlight text syntax?

L. Copy button next to Code blocks

[dbolack-ab]

Italics and bold use <em> and <strong> respectively. My understanding ( which may be wrong or outdated ) is that emphasis doesn't have a specific requirement for how emphasis is applied - just that the standard practice is italics in many/most language setups. strong is similarly weakly defined. As such, the only thing making *Thing* Italicize Thing is the style sheet. :)

I am rather loosey-goosey on the whole notion of changing things in potentially brew-breaking ways but changing the meaning of _ and __ seems pretty reasonable. I'm not sure that many folks who do a lot fo markdown use it over * patterns. Is there any way to survey? Scan actual brews?

[5e-Cleric]

The thing is that em and strong are usually better practice because you want screen readers to pick it up as strong or emphasized, but that is not an issue here, although there isnt much difference.

We tend not to want changing brew-breaking stuff, specially if there is no significant improval. But for v4 it'd be fine i reckon.

[5e-Cleric]

Based on the discussion on Gitter chat, the next syntax ideas might be the ones actually used in v4:

ELEMENT	v3 SYNTAX	v4 SYNTAX
headers	# to ###### header	# to ###### header
italics	*italics*	*italics*
bold	**bold**	**bold**
italicsbold	***italicsbold***	***italicsbold***
underline	<u>underline</u>	_underline_
strikethrough	~strikethrough~ OR ~~strikethrough~~	~strikethrough~ OR ~~strikethrough~~
link	[link](href)	[link](href)
right aligned text	{{text-align:right right aligned text}}	-: right aligned text
left aligned text	{{text-align:left left aligned text}}	:- left aligned text
center aligned text	{{text-align:center center aligned text}}	:-: center aligned text
list element	- list element OR * list element OR + list element	- list element (unsure if we should leave *)
ordered list element	x. list element OR i list element	x. list element OR i list element
📕	:book:	:book:
vertical space	::::	::::
line break	two spaces or \ at end of sentence, or <br>	two spaces or \ at end of sentence, or <br>
horizontal          space	horizontal :>>>>>>>> space	horizontal :>>>>>>>> space
inline term definition	Inline term::definition	Inline term :: definition (enforce spaces around ::)

---

Not agreed upon yet

ELEMENT	v3 SYNTAX	v4 PROPOSED SYNTAX
- caption	{{text-align:right -- caption}}	~caption

In all of these cases the syntax can be somehow achieved using curly spans or block syntax, i don't want to add it every time or this table would be big as hell.

If i have left something out, be sure to comment so i can edit this table.

[dbolack-ab]

Added #3909 For evaluating the non-breaking space token.

[5e-Cleric]

Regarding the * mode for ULs. I personally come to that pattern from word-processing which is probably where this comes from in the spec. I can't remember the last one I used that didn't convert some version of /^*/ into a bulleted list.

I expect removing that would cause more confusion than removing the other two modes would ( not that I have strong feelings about doing that instead )

I don't care the one we change, but - is the only one in my keyboard i can use without additional keys.

[dbolack-ab]

I don't care the one we change, but - is the only one in my keyboard i can use without additional keys.

Unless we wish to reuse one or more of those tokens elsewhere I don't think this is a valuable change.

[Gazook89]

I think we keep all three syntaxes for the lists. But I also see that i already said that in the next comment thread below this one, where Eric explains why.

[5e-Cleric]

i say again, i see why anyone would want 2, just don't see where the third one comes in handy. but alright, i'm not going to force this change.

[ericscheid]

Using - and + as alternative bullet list forms is actually useful .. because they get rendered as separate <ul>.

This brew source..

+ item
+ item
+ item

- item
- item

.. renders to

<ul>
  <li>item</item>
  <li>item</item>
  <li>item</item>
</ul>

<ul>
  <li>item</item>
  <li>item</item>
</ul

This is useful. I have used this when writing up long bullet list outlines where I want to keep different sections separate.

[ericscheid]

Mostly not.

Unless I'm using CSS like .page#p2 ul:nth-of-kind(3) .. because it's now all one huge bullet list with some <div class=blank> inserted inside list items.

I would have to resort to hacking up my source with {{curly-blocks}} to get the separation. A step backwards.

[Gazook89]

I am doubtful of how often this functionality gets used, but even so I think I am with Eric on this one. To match the current output we'd have to create more CSS and otherwise twist around to get the desired effect...and any effort spent doing that isn't worth breaking from the commonmark spec. And, the list syntax isn't +item, it's with the space + item....so I'm not sure that we gain anything from dropping those other list indicators anyway.

[dbolack-ab]

That is unfortunate.

[5e-Cleric]

i still don't think we need three separate syntaxes for the same thing.

[dbolack-ab]

i still don't think we need three separate syntaxes for the same thing.

Need? No. But lacking a reason to remove them, we maybe shouldn't?

[dbolack-ab]

What about adding thumbnail generation? It is fairly easy.

[5e-Cleric]

you mean outputting the first page of a brew as a png?

[dbolack-ab]

Essentially

[calculuschild]

A couple more possibilities:

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.

[dbolack-ab]

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.

Currently, the ToC generator runs entirely via DOM scraping, so anything like this would need to override the header parsing and add this field as a HTML attribute on the <H#> in question. I don't think this is a bad idea, but I'm unsure if this might interfere with the HeaderID addon?

[5e-Cleric]

I am not sure we want to pursue this route at all. I think, that indexes should be done by hand, once the brew is done. Same for ToC, is it a lot of work? absolutely. Could we help users with it? sure. But no feature is going to be perfect for any user. I think we should choose whatever method based on:

• ease of use
• ease to code
• flexibility of the method to create different outputs.

Perhaps the best thing we could do is some widget to let the user look for instances of a word in the text, like the search text feature, then collect the instances. Not while writing and cluttering the syntax, but later looking for that text programatically. And let me clarify that, ONLY when generating, not constantly.

@dbolack-ab @calculuschild What do you think?

[dbolack-ab]

I am not sure we want to pursue this route at all. I think, that indexes should be done by hand, once the brew is done. Same for ToC, is it a lot of work? absolutely. Could we help users with it? sure. But no feature is going to be perfect for any user. I think we should choose whatever method based on:

I'm at a loss here, particularly when the code has been done for months....

[5e-Cleric]

I do see how my comment would sound like nonsense

[dbolack-ab]

I do see how my comment would sound like nonsense

No, It doesn't come across as nonsense. However, it is antithetical to the idea of the Rich Indexes code.

That said a "simple" index that operated in this way might also be useful. If I was to select one or the other, I would, as a user, find the simple option very disappointing on a product that needed an index..

[Gazook89]

Table column width syntax as talked about here #1528

[5e-Cleric]

Do we need to wait till v4 for that? as long as we assume no numbers as the current behaviour we should be able to do this without breaking, no?

[dbolack-ab]

Working version: calculuschild/marked-extended-tables#456

[calculuschild]

Another proposal for V4: Change :::: "vertical spacing" to \\\\, and have it emit <br> instead of <div class="blank">

Already in CommonMark, we have a way to generate <br> 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. Thoughts?

[dbolack-ab]

Another proposal for V4: Change :::: "vertical spacing" to \\\\, and have it emit <br> instead of <div class="blank">

I just tested this and it doesn't look like it's directly supported by marked yet.

> text\

The rest was an easy switch.

If you were expecting our plugin to add it, is the above scenario supposed to emit

text<br>

or

text

followed by the parent container closing?

[ericscheid]

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:
To get a series of breaks. It seems we could just build on that to allow \\\\\ for multiple breaks:

Sounds elegant .. but with one wrinkle in the ointment.

The \ in commonmark is used to escape the following character. That is, ignore any syntactical meaning, applying the literal meaning — in this case ignoring the usually ignored inner-paragraph line break in the source text, and substituting in an actual line-break in the render text.

Thus, a question: does three backslashes at the end of a line (\\\¶) in source-text represent syntax for three line breaks in the render-text, or represent an actual literal backslash character ("") followed by a linebreak in the render-text?

[5e-Cleric]

I prefer colons for this, its way easier to input in my keyboard, because . and shift are so close together, as opposed to the backslash where i have to do 7 + shift

[Gazook89]

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}}](#p3)
  - #### [{{ dog}}{{ 3}}](#p3)
}}

we have this:

{{toc,wide
# Contents

- [{{ cat}}{{ 3}}](#p3)
  - [{{ dog}}{{ 3}}](#p3)
}}

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*](#p3)
  - [*dog*  *3*](#p3)
}}

[dbolack-ab]

The i element represents a span of text in an alternate voice or mood, or otherwise offset from the normal prose in a manner indicating a different quality of text, such as a taxonomic designation, a technical term, an idiomatic phrase from another language, transliteration, a thought, or a ship name in Western texts.

It is also a common practice for parts of ToCs, Appendices, and indices. Though to to be properly pedant here, we should be using <mark> , a class, or a style injection rather than using a tag that does the EXACT same thing.

I say, we keep using spans and ul for this. So i agree with just removing the headers from the syntax.

It's dumb redundancy, but sure.

[calculuschild]

The main reason for the two spans is to finagle the dot leaders working correctly. If you can figure out the CSS to remove one or both of those spans and still get the styling we want I am OK with that.

But I agree we shouldn't just substitute italics.

[Gazook89]

Quote from 5e's comment:

{{toc,wide
# Contents

1. [{{cat}} {{3}}](#p3)
  1.1. [{{dog}} {{3}}](#p3)
}}

Just noting that the above is not a functioning ToC, because it is missing the /space before cat, dog, 3, and 3. As-is, those would be empty spans with each of those strings as class names.

And I'm noting it because it supports the point that the {{ }} span syntax is not intuitive when you want a span with no additional attributes, and that's pretty much every span in a ToC.

Not a big deal when the ToC is auto-generated, just when someone is typing it out.

---

That said, i'm happy with just removing the header syntax but otherwise leaving it alone.

[ericscheid]

And I'm noting it because it supports the point that the {{ }} span syntax is not intuitive when you want a span with no additional attributes, and that's pretty much every span in a ToC.

We could write it as this, instead:

1. [{{entry: cat}} {{page: 3}}](#p3)
  1.1. [{{entry: dog}} {{page: 3}}](#p3)

I don't much like this approach (putting signs on things to explain how to use is a clear UX smell).

Alternatively, we could change the approach to (post-render) tweak the html links inside a {{toc}} block, and thus start with much simpler markdown of:

{{toc
1. [toc entry text](#p5 "106")
}}

Here the link title attribute is plucked out by a post-render plug-in to be the displayed page number.

[5e-Cleric]

hmmm

[Gazook89]

Font Imports

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.

[5e-Cleric]

I don't see that as being easier, if anything, abstracting it makes it harder to understand what each value is.
using font face you can see the numbers are font weights, not to mention you would still need the url there.
Opposed to this idea in this stage.