Allow authors to show/hide certain elements on deploy

[jamos-tay]

Follow up on discussion with @damithc on 19 Sep

The user may want to be able to show/hide certain elements from a page depending on the deploy configuration.

Cited use case:

When generating multiple sites with only slightly differing content, it might be easier to store all the information in one page, and allow the author to show/hide them. For example, if I have a Java tutorial page and a C# tutorial page, the text content can be exactly the same, only the code will differ:

# Print a line

<!-- Example syntax -->
<div class="require-flag --java">
    System.out.println("Hello world");
</div>
<div class="require-flag --Csharp">
    Console.WriteLine("Hello world");
</div>

The user can then deploy a Java or a C# version of the site without having two projects.

[damithc]

How about this? i.e., we tag divs using dummy classes.

<div class="java">
    System.out.println("Hello world");
</div>
<div class="Csharp">
    Console.WriteLine("Hello world");
</div>
<div class="Csharp Java">
    Some stuff
</div>

How do we tell markbind which tags to include/exclude?

[jamos-tay]

Hm, with that design then we have to use an exclude mechanism, otherwise markbind can't differentiate filtered elements with regular ones.

Exclude might be troublesome if you have a lot of different classes:

<div class="java">
...
<div class="csharp">
...
<div class="python">
...
<div class="c++">
...
<div class="c">
...

// Compile a Java version
exclude: ['csharp', 'python', 'c++', 'c']

But the exclude is just specified once inside the site.json, so I guess it's not really a big deal.

I also suggest standardizing a prefix to add to each class name (like say f-csharp, for filter, or --csharp) to mark the class as a filtered class, so they can be made distinct from normal classes. What do you think?

[yamgent]

I also suggest standardizing a prefix to add to each class name (like say f-csharp, for filter, or --csharp) to mark the class as a filtered class, so they can be made distinct from normal classes. What do you think?

Adding prefix will make it possible to support an include mechanism. However, there might be other libraries and frameworks that are also using the prefix in their class names, which means that they might get excluded by accident. So if we want to create a filter, we are better off with considering a new syntax, rather than relying on the class attribute and worrying about the conflicts.

[damithc]

I suspect this feature will need a good bit of discussion :-p
Another approach:

<div class="lang-java">
...
<div class="lang-csharp">
...
<div class="lang-python">
...
<div class="lang--cpp">
...
<div class="lang--c">
...

// Compile a Java version
include: ['lang--java']
exclude: ['lang--*']

The advantage of the above is that we can add more languages without breaking existing ones (due to wild-card exclude).

I don't mind using a new attribute too e.g., tags="lang--cpp, level--2"

Do we expect the configuration to happen at site.json level only? Maybe we need to show different variations of something within the same site?

[jamos-tay]

Adding prefix will make it possible to support an include mechanism. However, there might be other libraries and frameworks that are also using the prefix in their class names, which means that they might get excluded by accident. So if we want to create a filter, we are better off with considering a new syntax, rather than relying on the class attribute and worrying about the conflicts.

Well there's an (unclean) workaround for collision with other libraries, the user can simply choose class names that don't collide. We could also allow a custom prefix if needed (i.e., have a prefix config somewhere, but I don't think there's a large enough use case to warrant having one). But I agree that maybe we should consider using a custom attribute as those are used less often.

// Compile a Java version
include: ['lang--java']
exclude: ['lang--*']

Would having both imply some sense of priority? In this example, we have to exclude everything before including lang--java since lang--java matches lang--*. I'm worried having both include and exclude with wildcards may introduce a lot of edge cases (what to do with tags that match both, or none?)

Maybe we can specify a list of all possible tags first, then the ones to be included?

Do we expect the configuration to happen at site.json level only? Maybe we need to show different variations of something within the same site?

We could add an attribute into the front matter that overwrites site.json, this seems to be consistent with other features

[damithc]

include: ['lang--java']
exclude: ['lang--*']

Would having both imply some sense of priority?

I guess we need to work out a way to specify the two things in one shot. e.g.,

include: { type: 'lang', include: ['java']}

or, include: ['lang--java'] means automatic exclusion of other lang--* tags.

We could add an attribute into the front matter that overwrites site.json, this seems to be consistent with other features

We might also need a way to specify it as part of include

<include src="abc.md" tags="lang--java" />