This may have been discussed ad nauseam, but I’ll just throw it out here anyways:
What do people think about allowing bold and italic markers inside code blocks? When using MD for documentation of code, labs and sample code, the fact that it is near impossible to emphasize and highlight specific pieces of code is a real downer. In fact, it’s such a deal breaker that when I do write docs in MD, I use manual <pre> <code> blocks so I can embed bold / em tags inside the code.
For example:
<pre><code>
#include <stdio.h>
int main(int argc, char*argv[]) {
<b>printf("Hello world\n");</b> // --- Highlight this line
return 1;
}
</code></pre>
A naive suggestion considering the sparse use of repeated back quotes and/or tildes would be to have `` for bolding (and perhaps something akin for italic), etc?
#include <stdio.h>
int main(int argc, char*argv[]) { printf("Hello world\n"); // — Highlight this line
return 1;
}
There are various extensions out there which I’d rather pass on, given that this seems such a common pattern and need when writing code documentation, I want to see what people’s opinion on this are?
Some existing parsers, such as Python Markdown [1], use a “hl_lines” option after the language. Example:
The spec allows an “info string” after the initial backticks. The spec only mandates interpretation of the first word of this info string (which is used as the “language” of the code block). The rest is free form, and a renderer can do what it likes with this. So, nothing in the spec prevents you from writing a renderer that looks in the info string for something like hl_lines=3 and adds line numbers to the highlighted code.
Which part of is this a terrible idea? I am curious to know if (besides implementation issues) the mere idea of emphasizing selected sections inside a code block is considered harmful? It is of tremendous value to me and my target audience.
>>No, it should not be part of core. Highlighting of code blocks should happen as separate plugins.
Remember that a Markdown and CommonMarkcode block is actually tree features (or behaviors, or processing options) rolled into one:
Choosing a monospace font;
Suppressing white space normalization, ie SPACE and EOL are taken “literally”;
Suppressing parsing (ie CommonMark markup is not recognized).
In SGML/HTML/XML these can be “chosen” independently:
The font can be selected by any old style style sheet language, from DSSSL (yay!) over CSS (yawn!) to XSLT/XSL-FO (yuk!), or just use <code>;
White space handling can be influenced by using a xml:space attribute or <pre> element;
Parsing suppression is the purpose of marked sections, usually “CDATA sections” in XML: <![CDATA[ … ]]>.
Maybe an extension of the code block syntax in CommonMark could allow to choose from these three options independently, too? (Right now, I can only think of some incantations in the info string …)
I would spontaneously think that the “Highlight this line” feature should go into the comment (which may look different depending on the language) and the “codeword” should be indicated at the fence:
Indicating the line has the advantage of not changing the code at all, but changing or adding comments is quite unobtrusive and you don’t risk that the line numbers change due to changes in the code itself.
@illionas I think this is still less natural than just using HTML code blocks, but I think this is definitely better because it’s robust against modifying the code (i.e.: adding or removing lines).
I think just using code blocks in HTML is the best solution to this. Needing to substitute < with < only seems to be necessary for things that look like HTML tags (e.g.: #include <iostream>, but not x < 0: https://goo.gl/Yj8J9v). Obviously the worst case would be trying to markup an HTML code snippet, but for most languages I think it won’t be too onerous.
The only issue I see (and I’m not sure if this is a bug or WAI) is that a newline after <pre><code> get interpreted as part of the code block, so you need to put the first line of your code block on the same line as <pre><code> (see again the link above).