I think that would be fine; markdown is technically defined as a superset of html, so including html elements inside of a markdown document is valid. Complex tables might become cumbersome to read without rendering, but I agree that the markdown tables are limited in form (and not actually part of the "core" markdown spec!). Any thoughts, @ethanrd, @lesserwhirls, @dopplershift ?
Table support in Markdown is an interesting beast. The core spec (referred to here as 'basic syntax') omits them, but a common syntax was adopted pretty quickly in various extended-syntax markdown specs (multimarkdown, github-flavored markdown spring to mind). The issue with these extended specs is they include tables, yes, but also dozens of other things that completely ruin the 'human readable raw text files' aspect of Markdown. I mean, multimarkdown supports mathTeX but it's not much fun to read in the raw text ;). Anyways, this has resulted in non-uniform support in WYSIWYG markdown editors, where tables render differently, or not at all, depending on the editor/rendering engine.
It just seems like a real omission on the part of John Gruber when he designed markdown, unless his intent was to use embedded html for more complex features in the first place.
Table formatting is hard, and I'm guessing Gruber thought the chances of doing better than HTML for the general case were slim to none. The fact that the various flavors of markdown have come up with different approaches even for the 50% case (simple tables with no control over column widths/row heights) speaks to the fact that people have different expectations/priorities for rendered tables -- do they have column headers? Row headers? nesting? HTML table formatting may not be easy to read, but at least it can be read and is widely understood.
The markdown omission I can't understand is leaving out the ability to associate individual elements with a CSS class.
@ddirks I suspect that's because the raw text files are meant to be human readable; his motivation, as I recall from an interview, was to capture the ways people write in raw text (bullet points, emphasis, sections/subsections, etc) and provide a processor for generating html. The markdown processors seem to be where the CSS style sheets are injected; I infer this because every 'live preview' editor I use offers a variety of styles to choose from, when viewing the rendered document.
That said, now I wonder; since raw html is valid markdown, can you use the appropriate raw html to associate elements with a CSS class?
For sure - you can always fall back on raw HTML for the more tricky stuff. Kramdown (a common flavor of markdown) has a syntax for adding IDs and classes, but I don't believe Doxygen's extensions to markdown does.
I've never found a way to associate CSS classes with specific elements -- but if there's a way, I'd love to hear about it.
You're right that the CSS is injected when markdown is translated to HTML, so document-level style sheets are (relatively) easy to associate with markdown documents. As for the "human readability" advantages of markdown over other markup schemes, I'd argue it's a matter of convention and familiarity. To say that
###Heading
is inherently significantly more readable than
<h3>Heading</h3>
seems a bit of a stretch to me. Easier to type, sure, but the markdown doesn't convey more meaning to a human than the HTML.
<soapbox>
My argument would be that since markdown is intended to be rendered as HTML, and since HTML syntax is allowed in markdown files, markdown syntax is really just a set of shortcuts to writing HTML, mediated by a preprocessor. Why not include an optional markdown shortcut for associating a CSS class with an HTML element? Gruber's argument is that this defeats the point of markdown, and you should just use HTML if you need to get so fancy with the styling. I agree with Gruber up to the point where we are trying to use markdown as direct input into a publishing system (for, say, software documentation) where a full range of text formatting is arguably required. If there's a benefit to using markdown coding as a source for published documentation, then there's a benefit to expanding the correlation between markdown and "real" HTML to the point of maximum utility. To me, this would mean letting authors use simplified coding syntax while retaining the power of the underlying language (HTML) to present information in ways that are useful to readers.
</soapbox>
Not that this has any bearing on what to do in the NUG. In this case, where we do want nicely formatted tables for our readers, inserting them in HTML is the best option I can think of. HTML tables are a pain, though -- if it makes things easier, there are a variety of online HTML table generators out there to create the skeleton code. Like any sort of algorithmically generated code, HTML table code can be problematic. One of the better generators (IMO) is from RapidTables. In this context, my suggestion would be to turn off all of the table styling (except table caption) when generating the table skeleton and let our custom CSS handle the appearance.
Sorry for the lengthy reply. I get overenthusiastic when people evince interest in the visual appearance of written information...
Hi Doug, no problem, I'm just excited I get to talk about Markdown; most people I talk about it with are only briefly engaged, and I love talking about Markdown :).
<h3>heading</h3>
is as readable as ### heading, perhaps, but I think you dismiss how important "it might be easier to type" is. If somebody sent me a raw html file to read and comment on, in plain text, I'd ask them to please not. If they asked me to write raw html, I'd write it in Markdown; if they persisted, I'd use pandoc to convert to raw, unstyled html. Markdown is just a great shortcut for me to write the way I would normally write (and not just for blog publishing, but on github, or my various note taking application) but end up with something that renders nicely. But, I think I've simply reiterated the point you made. I hate to discard that work so I'll leave it here ;).
It is worth noting that, pursuant to the conversation in the last NUG meeting, we are going to try to move away from doxygen as a required component to the NUG documentation. I expect there will always be a hook where you can run doxygen to generate the html (or LaTeX or what have you) but ultimately, the raw markdown files will be readable and useful without requiring doxygen-specific processing.
I'm also now wondering if there is a flavor of Markdown that does what you want? Core Markdown + extensions for the web professional, who wants the extended functionality you've described but that wouldn't be used by the majority of users. I mean, an html document is a markdown document, it just doesn't use any markdown syntax.
Don't get me wrong, I think markdown is great. And I don't dismiss the "easier to type" and "easier to read" aspects in the least.
(I formatted my undergrad senior thesis using troff, so I think I know whereof I speak... ;-)
Markdown is an excellent way to convey semantic structure in plain-text documents. If you're looking at plain-text documents, I think it's difficult to beat.
But.
Because Markdown is so often rendered using HTML, people treat it like a typesetting system. And for a significant fraction of documents, it does just fine. It hits the sweet spot of ease of authoring (for those who like text editors, anyway) and easy-to-read output. Who would choose TeX when all they need is headings and paragraphs and lists and links?
The minute you need finer-grained control over the appearance of your text, though, you're back to needing the capabilities of the underlying language. Say you want to fit your documents into a larger design scheme, where there are text wraps and icons and sidebars and fancy tables with scroll bars and frozen heading rows. When you make that transition, from plain-text documents to "designed" documents, you move out of the sweet spot. Which is perfectly fine, as long as you make conscious trade-offs between the perceived ease of authoring (more markdown, less HTML) and perceived ease of reading (what all those "design" features are meant to improve, leading to more HTML).
My own training/background/job leads me to always prioritize the needs of the many (readers) over the needs of the few (authors). But making things easier for authors is good for readers! So my wish to add CSS capabilities in markdown is really a wish to enlarge the sweet spot just a bit, gaining an improvement for readers at the cost of a slight inconvenience for authors. Gruber didn't see it that way, and more power to him.
Using flavored markdown to add capabilities is all well and good, as long as you can live entirely in the flavored ecosystem. That's difficult too, though -- right now, we've got markdown preprocessors that will accept various flavors building some of our documentation, but (for example) the blog only understands vanilla markdown.
So I guess my position is that if the markdown source files are meant to be read as markdown, they should be written in as vanilla-markdown a manner as the author can stomach, so the greatest number of readers can read them. If, on the other hand, the markdown source files are meant to be input into a publishing system, then they should be written in markdown that is enhanced as much as the author can stomach, to give the most typographical control. In the case of the NUG, and documentation source files in general, I'd say that reverting to HTML snippets for anything vanilla markdown can't do is the cleanest solution we currently have.
ASIDE: If Gruber had broken his rule of no markdown formatting inside HTML block-level elements and allowed markdown inside a <div> element, I would have been perfectly happy! Well, reasonably happy, anyway.
Just so you know, my level of fervor about this topic is dramatically lower than it has been in some of my past lives... 8->
A simple paragraph with an ID attribute.
{: #para-one}
span level:
This *is*{:.underline} some `code`{:#id}{:.class}.
I use this feature in the netCDF-Java and TDS docs to get links to open in a new window by attaching a target=_"blank" attribute to the <a> element:
[NetCDF-4 C library](https://www.unidata.ucar.edu/software/netcdf/){:target="_blank"}
Not too bad, but only useful if you have bought into a system that uses (or parses) kramdown (which is the default used by Jekyll, and one of two options for GitHub Pages).
Leave it to Sean to interject practical sanity into my philosophical ranting!
Kramdown's additions all seem like improvements. I wish "the markdown community" (whatever that actually is) could just pick a variant that is a superset of standard markdown and agree on that...
Failing a clear community-wide winner, should we (Unidata) just pick one and go?
I would propose that html
I think that would be fine; markdown is technically defined as a superset of
html, so includinghtmlelements inside of a markdown document is valid. Complex tables might become cumbersome to read without rendering, but I agree that the markdown tables are limited in form (and not actually part of the "core" markdown spec!). Any thoughts, @ethanrd, @lesserwhirls, @dopplershift ?I think that seems reasonable, especially for the last part about not being part of the core spec.
Table support in Markdown is an interesting beast. The core spec (referred to here as 'basic syntax') omits them, but a common syntax was adopted pretty quickly in various extended-syntax markdown specs (multimarkdown, github-flavored markdown spring to mind). The issue with these extended specs is they include tables, yes, but also dozens of other things that completely ruin the 'human readable raw text files' aspect of Markdown. I mean, multimarkdown supports mathTeX but it's not much fun to read in the raw text ;). Anyways, this has resulted in non-uniform support in WYSIWYG markdown editors, where tables render differently, or not at all, depending on the editor/rendering engine.
It just seems like a real omission on the part of John Gruber when he designed markdown, unless his intent was to use embedded html for more complex features in the first place.
Table formatting is hard, and I'm guessing Gruber thought the chances of doing better than HTML for the general case were slim to none. The fact that the various flavors of markdown have come up with different approaches even for the 50% case (simple tables with no control over column widths/row heights) speaks to the fact that people have different expectations/priorities for rendered tables -- do they have column headers? Row headers? nesting? HTML table formatting may not be easy to read, but at least it can be read and is widely understood.
The markdown omission I can't understand is leaving out the ability to associate individual elements with a CSS class.
@ddirks I suspect that's because the raw text files are meant to be human readable; his motivation, as I recall from an interview, was to capture the ways people write in raw text (bullet points, emphasis, sections/subsections, etc) and provide a processor for generating html. The markdown processors seem to be where the CSS style sheets are injected; I infer this because every 'live preview' editor I use offers a variety of styles to choose from, when viewing the rendered document.
That said, now I wonder; since raw html is valid markdown, can you use the appropriate raw html to associate elements with a CSS class?
For sure - you can always fall back on raw HTML for the more tricky stuff. Kramdown (a common flavor of markdown) has a syntax for adding IDs and classes, but I don't believe Doxygen's extensions to markdown does.
I've never found a way to associate CSS classes with specific elements -- but if there's a way, I'd love to hear about it.
You're right that the CSS is injected when markdown is translated to HTML, so document-level style sheets are (relatively) easy to associate with markdown documents. As for the "human readability" advantages of markdown over other markup schemes, I'd argue it's a matter of convention and familiarity. To say that
###Headingis inherently significantly more readable than<h3>Heading</h3>seems a bit of a stretch to me. Easier to type, sure, but the markdown doesn't convey more meaning to a human than the HTML.<soapbox>My argument would be that since markdown is intended to be rendered as HTML, and since HTML syntax is allowed in markdown files, markdown syntax is really just a set of shortcuts to writing HTML, mediated by a preprocessor. Why not include an optional markdown shortcut for associating a CSS class with an HTML element? Gruber's argument is that this defeats the point of markdown, and you should just use HTML if you need to get so fancy with the styling. I agree with Gruber up to the point where we are trying to use markdown as direct input into a publishing system (for, say, software documentation) where a full range of text formatting is arguably required. If there's a benefit to using markdown coding as a source for published documentation, then there's a benefit to expanding the correlation between markdown and "real" HTML to the point of maximum utility. To me, this would mean letting authors use simplified coding syntax while retaining the power of the underlying language (HTML) to present information in ways that are useful to readers.</soapbox>Not that this has any bearing on what to do in the NUG. In this case, where we do want nicely formatted tables for our readers, inserting them in HTML is the best option I can think of. HTML tables are a pain, though -- if it makes things easier, there are a variety of online HTML table generators out there to create the skeleton code. Like any sort of algorithmically generated code, HTML table code can be problematic. One of the better generators (IMO) is from RapidTables. In this context, my suggestion would be to turn off all of the table styling (except table caption) when generating the table skeleton and let our custom CSS handle the appearance.
Sorry for the lengthy reply. I get overenthusiastic when people evince interest in the visual appearance of written information...
Hi Doug, no problem, I'm just excited I get to talk about Markdown; most people I talk about it with are only briefly engaged, and I love talking about Markdown :).
is as readable as
### heading, perhaps, but I think you dismiss how important "it might be easier to type" is. If somebody sent me a raw html file to read and comment on, in plain text, I'd ask them to please not. If they asked me to write raw html, I'd write it in Markdown; if they persisted, I'd usepandocto convert to raw, unstyled html. Markdown is just a great shortcut for me to write the way I would normally write (and not just for blog publishing, but on github, or my various note taking application) but end up with something that renders nicely. But, I think I've simply reiterated the point you made. I hate to discard that work so I'll leave it here ;).It is worth noting that, pursuant to the conversation in the last NUG meeting, we are going to try to move away from doxygen as a required component to the NUG documentation. I expect there will always be a hook where you can run doxygen to generate the html (or LaTeX or what have you) but ultimately, the raw markdown files will be readable and useful without requiring doxygen-specific processing.
I'm also now wondering if there is a flavor of Markdown that does what you want? Core Markdown + extensions for the web professional, who wants the extended functionality you've described but that wouldn't be used by the majority of users. I mean, an html document is a markdown document, it just doesn't use any markdown syntax.
</thinking out loud>
Don't get me wrong, I think markdown is great. And I don't dismiss the "easier to type" and "easier to read" aspects in the least. (I formatted my undergrad senior thesis using troff, so I think I know whereof I speak... ;-)
Markdown is an excellent way to convey semantic structure in plain-text documents. If you're looking at plain-text documents, I think it's difficult to beat.
But.
Because Markdown is so often rendered using HTML, people treat it like a typesetting system. And for a significant fraction of documents, it does just fine. It hits the sweet spot of ease of authoring (for those who like text editors, anyway) and easy-to-read output. Who would choose TeX when all they need is headings and paragraphs and lists and links?
The minute you need finer-grained control over the appearance of your text, though, you're back to needing the capabilities of the underlying language. Say you want to fit your documents into a larger design scheme, where there are text wraps and icons and sidebars and fancy tables with scroll bars and frozen heading rows. When you make that transition, from plain-text documents to "designed" documents, you move out of the sweet spot. Which is perfectly fine, as long as you make conscious trade-offs between the perceived ease of authoring (more markdown, less HTML) and perceived ease of reading (what all those "design" features are meant to improve, leading to more HTML).
My own training/background/job leads me to always prioritize the needs of the many (readers) over the needs of the few (authors). But making things easier for authors is good for readers! So my wish to add CSS capabilities in markdown is really a wish to enlarge the sweet spot just a bit, gaining an improvement for readers at the cost of a slight inconvenience for authors. Gruber didn't see it that way, and more power to him.
Using flavored markdown to add capabilities is all well and good, as long as you can live entirely in the flavored ecosystem. That's difficult too, though -- right now, we've got markdown preprocessors that will accept various flavors building some of our documentation, but (for example) the blog only understands vanilla markdown.
So I guess my position is that if the markdown source files are meant to be read as markdown, they should be written in as vanilla-markdown a manner as the author can stomach, so the greatest number of readers can read them. If, on the other hand, the markdown source files are meant to be input into a publishing system, then they should be written in markdown that is enhanced as much as the author can stomach, to give the most typographical control. In the case of the NUG, and documentation source files in general, I'd say that reverting to HTML snippets for anything vanilla markdown can't do is the cleanest solution we currently have.
ASIDE: If Gruber had broken his rule of no markdown formatting inside HTML block-level elements and allowed markdown inside a
<div>element, I would have been perfectly happy! Well, reasonably happy, anyway.Just so you know, my level of fervor about this topic is dramatically lower than it has been in some of my past lives... 8->
Here is what kramdown does for block level and span level elements. For a quick example, block level:
span level:
I use this feature in the netCDF-Java and TDS docs to get links to open in a new window by attaching a
target=_"blank"attribute to the<a>element:Not too bad, but only useful if you have bought into a system that uses (or parses) kramdown (which is the default used by Jekyll, and one of two options for GitHub Pages).
Leave it to Sean to interject practical sanity into my philosophical ranting!
Kramdown's additions all seem like improvements. I wish "the markdown community" (whatever that actually is) could just pick a variant that is a superset of standard markdown and agree on that...
Failing a clear community-wide winner, should we (Unidata) just pick one and go?
Barring a community-wide winner, I think we need to stick with whatever is most broadly supported, which would be core Markdown w/ embedded HTML.