Update site.json and frontmatter tag behavior

[jamos-tay]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [X] Enhancement to an existing feature

Follow up from #467

What is the rationale for this request?

The current tagging overwrite behavior is too aggressive. We want to support the following use case:

helloWorld-fragment.mbdf:

<div tags="level--beginner">
This is how you do Hello World:
<code tags="lang-cs">Console.WriteLine("Hello World");</code>
<code tags="lang-java">System.out.println("Hello World");</code>
</div>
<div tags="level--advanced">
Let's do a refresher. Recall that to print anything, you would use <code tags="lang-cs">Console.WriteLine()</code><code tags="lang-cs">println()</code>.
<question>
How would you print the string "Hello World"?
...
</question>
</div>

index-cs.mbd:

<frontmatter>
tags: lang-cs
</frontmatter>
<include src="helloWorld-fragment.mbdf" />

index-java.mbd:

<frontmatter>
tags: lang-java
</frontmatter>

What changes did you make? (Give an overview)

Introduced group tags. Group tags are represented as group--tagName. No changes to current tag syntax, e.g. tags: ['lang--java', 'lang--c++', 'level--advanced']. (I think this is more convenient than using an object { lang : java }, also it is consistent with usage in html files)

Instead of overriding, site and frontmatter tags are merged, but only one tag of a single group will be applied. For example:

site.json : ['a', 'b', 'lang--java']
frontmatter : ['c', 'd', 'lang--cs', 'level--beginner']
Merged: ['a', 'b', 'c', 'd', 'lang--java', 'level--beginner']

Only the first -- matters, tags like ['group--Name--name'] are possible
Tags without -- are treated as a group tag with no name, they can be used on their own. We don't have to worry about overriding behavior for these.

Users can turn off tags completely by specifying a non-existent tag name:

site.json : ['lang--off', 'x--off']
frontmatter : ['lang--java', 'x']
lang--java and x tags will no longer show.

Is there anything you'd like reviewers to focus on?

Does the above behavior work? I'm open to revising it.

I'll update the documentation if it's okay.

[yamgent]

site.json : ['lang--off', 'x--off']
frontmatter : ['lang--java', 'x']
lang--java and x tags will no longer show.

Seems reasonable for now, although that means that if authors really use lang--off as a tag name it would be mildly confusing.

Also, I see x as a tag with no group, rather than a group with no actual tag name. Another potential source of confusion?

[damithc]

Instead of overriding, site and frontmatter tags are merged, but only one tag of a single group will be applied.

Will there be a need to allow more than one tag? e.g., level--basic and level--intermediate tags need to be allowed to create a document for intermediate level readers (they need to see basic level stuff too).

---

Another approach is to have a mechanism like the following (assuming we allow tags to be specified at the point of inclusion too): * means all, + means show, - means hide; tags applied left to right, cumulatively.

• file has content tagged with level.1, level.2, level.3
• frontmatter has the tags: -level.*, +level.1 → only level 1 stuff are shown by default
• at the point of inclusion we specify +level.2 → when applied on top of frontmatter tags, levels 1-2 stuff are shown
• site.json: -level.*, +level.3 → only level 3 stuff are shown now

[yamgent]

Another approach is to have a mechanism like the following (assuming we allow tags to be specified at the point of inclusion too): * means all, + means show, - means hide; tags applied left to right, cumulatively.

• file has content tagged with level.1, level.2, level.3
• frontmatter has the tags: -level.*, +level.1 → only level 1 stuff are shown by default
• at the point of inclusion we specify +level.2 → when applied on top of frontmatter tags, levels 1-2 stuff are shown
• site.json: -level.*, +level.3 → only level 3 stuff are shown now

I think this approach is the best, it allows the author to have ultimate control over how the overriding behaviour works. Let's do that.

[jamos-tay]

Hmm okay, seems doable

[jamos-tay]

Updated

* matches any number of characters (.*).
- hides all tags matching the expression.
+ is optional so both +tag and tag are the same, this maintains old functionality.
Tags are processed left to right
Front matter tags are processed first, then site json tags

[yamgent]

Apologies for the late review!

[jamos-tay]

Updated

[yamgent]

Need you to resolve merge conflicts.

[jamos-tay]

Rebased

[yamgent]

Need you to resolve conflict again. :P I will merge this first next time.

[jamos-tay]

Rebased