language-markdown uses "important" class

[garretwilson]

Arg, this is biting me again. Just like in #1044, the language-markdown plugin seems to be using a class of important to style sections of code. So if I have:

## FooBar

It gets rendered:

<span class="token title important"><span class="token punctuation">##</span> FooBar</span>

As discussed in #1044, the style "important" is not semantically reflective of the particular thing being styled. Plus because the word important is so general, it's likely to already have a style (for another purpose). So now I get big exclamation marks in the middle of my Markdown.

@aviaryan, maybe this is something you can address like you did in #1047 ?

[Golmote]

I'd argue that titles are indeed important. That seems quite semantic to me.

There are many classes we use that are likely to already have styles: tag (on blog posts for example), comment (blog posts too), symbol and entity (quite generic terms too)... We can't take everyone's stylesheets into account. Those classes are semantic in the context of the languages they are used in.

If your own styles do not play well with Prism's ones, then you might just need to write a bit of CSS to fix this.

[garretwilson]

I'd argue that titles are indeed important. That seems quite semantic to me.

By that argument, everything is important. What, is the text less important than the titles?

In fact if you study law you'll learn that the titles of statutes and contracts are usually less important than the text, as they are given for simple organization purposes and do not provide any additional normative weight to the text. Learn more about this reading about the "Headings clause".

The purpose of the Prism markup is to show syntax highlighting for the various formats. So maybe I should better state my case by saying that if the style is going to be so general, it should be a noun, not an adjective.

Let's not make this complicated: Prism found a Markdown heading. So it should give it a style of "heading". Whether the heading/title is "important" or not is not for Prism to decide; that's an opinionated judgment call. Just mark it as a Markdown heading, which is what it is, and we'll all be happy. If I have CSS code using "heading" or "title", then I'll modify it so that it doesn't apply to Prism. But my beef is that Prism has no business trying to tell me what is "important" or not.

Just my opinion---but I think my reasoning here not too far off.

[Golmote]

And I'm pretty sure @LeaVerou will agree with you.

The important class was initially used for the !important keyword in CSS. And the reuse of classes in Prism, useful to prevent constantly BC breaking all existing themes (including the "non-official" ones), is already subject to debate and considered an issue (#1055). Anyway, I made my point.

[LeaVerou]

@garretwilson The problem is that we need to reuse token names across languages, otherwise every theme would need to be updated for every language, which as you can imagine, does not scale. It's indeed a tough problem, if you have any ideas, please post them in #1055. However, complaining about the current state of things without proposing an alternative is not very productive for any of us.

[garretwilson]

@LeaVerou I wasn't aware of the wider problem. I was just making you aware of the immediate problem, which had been addressed in #1044 for another language. If there is a wider problem, sure I'll look into it and see if I have any ideas. But in for the immediate issue, are you saying that you addressed it for language-ini but you don't intend to address in the same way for language-markdown? I'm just trying to clarify what you're saying.

[garretwilson]

For you to understand better why this is such a problem, and why I cannot just set up my stylesheet selectors to ignore things inside <code> blocks, consider this excerpt from the lesson on "inheritance" in my Java programming class (I'm writing the materials):

<pre><code class="language-java">final Vehicle vehicle = new Airplane();
  vehicle.move(); //<span class="important">invoked Airplane.move()</span></code></pre>

Note that I have my own style for important that I want to show up inside the code block! For java-language this is working beautifully. But for language-markdown, as you saw above, Prism decides it wants to make other things important (even though they have nothing to do with the semantics of "important"), so my styles start appearing in unrelated places.

You're right that it is only coincidental that there is a semantic mismatch here; it is possible in other cases that Prism might use a style with the correct semantics related to a code block, yet it would incorrectly bring in a style I had of the same name. So I acknowledge that there is a bigger issue here: namely, of style name clashes. But name clashes is by no means a new issue in computing. Why not simply prefix all Prism styles with some sort of "namespace" prefix, e.g. "prism-"?

But suggestions for resolving name clashing I'll post on #1055. For this present issue, I reiterate that "important" is not semantically correct in the first place, and if we change it as was done in #1044 this will buy us time for addressing #1055. Do you see where I'm coming from, and what do you think?

[Golmote]

Another issue is that, to be semantically correct in all languages, Prism would have to use a huuuge number of different classes, which do not currently exist in the themes stylesheets. The title class (markdown example) does not exist in the themes.
Other languages use other vocabulary: verbs, adverbs, directives, flags, blocks, lists, tables, commands, labels, rules, macros, enums, registers, atoms, sigils, captures, parameters, filters, dates, conjunctions, mixins, keys, annotations, targets, vectors, matrices, constructors, shortcuts, maps, sequences... All those names should, semantically, have an associated CSS class in Prism's themes. But we can't do it the way we handle themes currently.

[Golmote]

The recent issue #1119 made me think that you might want to use this plugin to solve your problem. I'll close this issue, though, since there is no obvious way to solve it in the near future.

[garretwilson]

The recent issue #1119 made me think that you might want to use this plugin to solve your problem.

@Golmote I was overjoyed to see that plugin, but then I saw that I will need to go back and modify all of my documents, adding a new code segment with custom JavaScript to all my pages!

Is there no way someone could provide a version of this plugin with a default prefix, so that Prism simply automatically uses a prism- prefix, for example?

It is a lot of overhead to not only force my authors to add extra JavaScript to all pages --- not only for future documents, but for all past document! (If there were an option to include this in Prism, we could easily update it across the board by simply updating the shared CSS/JS file.)

[garretwilson]

The recent issue #1119 made me think that you might want to use this plugin to solve your problem.

I can't try it yet, because the download mechanism seems to be broken; see #1136 .