I think it would be nice to be able to have a standard for single and multiline comments that aren’t rendered.
single line:
! not rendered
multiline
!!!optional-label
not rendererd
neither is this.
!!!
If the compiler returned the labelled comment blocks (as a key:string value:string collection) in addition to the compiled output that would be beneficial.
As an aside, this could be used as a boilerplate for generator directives… I’d considered abusing the link labels.
instead of:
[publish] # (2015-01-01)markdown
[title] # (Happy New Year)
can put it in a labelled comment block
!!!directives
{
"publish":"2015-01-01",
"title":"Happy New Year!"
}
!!!
Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
I think comments should be separate from the content to keep the content uncluttered and readable as-is.
Well a comment character like % in the beginning of the line doesn’t render the doc unreadable or make it look marked up. It’s just a place for notes to self while, say, writing a novel, which a lot of people are doing nowadays using Markdown.
If I were going to publish the doc as plain text, I’d run a filter script and take out the comments, but until then I’m going to be publishing it via pandoc, so I guess the other alternative is to just use the pandoc filters scripts.
If metadata blocks (beyond the document header) are going to become a CommonMark extension, using these blocks for comments is sensible, especially as it eliminates the need for a specific Markdown comment syntax.
The Pandoc README states that a YAML metadata block can be terminated with either three hyphens or three dots. What was the reasoning behind this? I personally like the use of hyphens as a delimiter for both the start and end of the block (consistent with other parts of Markdown that use matching delimiter pairs). I see a potential clash with the horizontal rule syntax though.
If metadata blocks (beyond the document header) are going to become a CommonMark extension, using these blocks for comments is sensible, especially as it eliminates the need for a specific Markdown comment syntax.
The Pandoc README states that a YAML metadata block can be terminated with either three hyphens or three dots. What was the reasoning behind this? I personally like the use of hyphens as a delimiter for both the start and end of the block (consistent with other parts of Markdown that use matching delimiter pairs). I see a potential clash with the horizontal rule syntax though.
The three dots YAML’s standard way of signalling the end of a YAML document within a larger file, so that’s why I used it originally. But by then the use of three hyphens for enders had caught on in Jekyll, Hackyll, etc., so I supported both.
I wasn’t actually making any concrete proposals about CommonMark here (either metadata or comments), just an observation about pandoc.
Hi, all. I’ve just been alerted to this discussion in an email exchange with the iA Writer developers, after I made a feature request for a better comments syntax.
I echo @Rick here in thinking about authors writing books: I’m an editor by profession and I often encourage people to explore Markdown as a way of learning to write in a more structured way and without dealing with the often horrendous formatting problems they create for themselves in Word. Commenting, as is available in LaTeX and in many programming languages, is also a great tool for collaborating and for making cuts to a manuscript without destroying the original text.
Overall, the sentiment here seems to be “we already have HTML comments—what do we need another syntax for”? From my perspective, here are the two main reasons:
HTML comment syntax is not Markdown-y. Unlike most other formatting, which needs a single character at the beginning of a line, or a single character either side of a formatted word or phrase, HTML comments require a minimum of 3 characters on either side … and the characters on each side are different (<!-- on the way in and --> on the way out).
Because it’s not Markdowny, it’s not likely to ever be adopted by non-technical users. It’s harder to learn, harder to type, and because it’s not actually Markdown, but HTML, it is often not included in vendor-provided guides to Markdown (eg, Github’s Mastering Markdown document.)
Put another way, non-technical Markdown users, and software vendors whose products are aimed at them, could use a comment syntax that is part of Markdown, not a workaround that involves learning other forms of markup that various Markdown parsers support (HTML, YAML, etc.)
My suggestion for the characters to be used would be % or %% (which matches LaTeX and the block comments in Ulysses), or //, which is used in Asciidoc. Something that is shared with other markup languages that Markdown users may also use would be preferable. This could be used in a variety of ways, eg,
# Start of line
% This whole paragraph is a comment.
# End of line
Lorem ipsum. % What comes after the mark is a comment.
But the next line is not a comment.
# Around phrase
Lorem %this is a comment% ipsum.
# Fenced
%%%
This is a comment.
And so is this.
%%%
There is a conflict between making it readable as plain text and allowing
four different ways of commenting. Unless your hypothetical “non-technical
Markdown user” relies on syntax highlighting it could be tricky reading
end-of-line and around-phrase comments. Easy for programmers because it’s
second nature. Maybe not for regular writers and readers?
Maybe consider just start-of-line and fenced? But I seem to recall there
were other issues with this. And it wasn’t an easy thing to add?
Even just a beginning of line comment would do, at a minimum.
Essentially, the blockquote syntax, but with a different symbol, would be enough for most use cases.
Fenced would probably be the next most useful, as it would enable easy commenting out of larger sections, such as the whole of a passage between two subheadings in an essay, or a whole book chapter.
Applications that might introduce non-technical users to Markdown, such as iA Writer, Byword, and Ulysses (which has its own extensions to standard Markdown) tend to have some form of syntax highlighting for most Markdown elements, if not all.
Pandoc already supports% at the start of each line for comment syntax, and as @benhourigan pointed out, it’s more Markdownish than HTML comments. I don’t think we need to have so many different ways to add comments, such as partially commented lines and fenced blocks. To keep things simple we can use the same rules as block quotes. Instead of > for starting a block quote, use % to start a comment. Require the symbol at the start of each paragraph that is to become a comment. This, together with line blocks for pre-formatted text, would compliment the existing block quote syntax and feel like part of the same language, rather than adding a fenced block syntax for comments which would not feel like part of the same language.
It’s also not a problem commenting out whole sections without a fenced block syntax, assuming the writer has a good editor. Ctrl+/ for commenting/uncommenting a block works in a number of popular code editors such as Atom and Visual Studio Code; this shortcut could be added to popular Markdown editors as well.
There has been some talk of using Jekyll-style blocks for metadata, variations of which are used in both Pandoc and MultiMarkdown. If we do go down this route, this block could be used as the basis for comment block syntax too. They are the same semantic family: extra information that is not rendered in the HTML output, so there’s less cognitive overhead for people learning the syntax (technical users or otherwise). But it would be simpler to have just one metadata syntax, so perhaps % at the start of every line could be used for other metadata too, and not have a block syntax for metadata. e.g. to include metadata about the document, just include these comments before everything else:
% Title: A Sample MultiMarkdown Document
% Author: Fletcher T. Penney
% Date: February 9, 2011
% Comment: This is a comment intended to demonstrate
metadata that spans multiple lines, yet
is treated as a single value.
% CSS: http://example.com/standard.css
I’ve also recategorised this topic under Extensions and added it to the list of proposed extensions, since the core CommonMark spec focuses on features found in the original Markdown spec.