Does Markdown support comments?

General Usage
,
1

I am writing docs for a package, using Emacs, and I want to put some file local variables in the markdown files, I tried:

[//]: # -*- mode: auto-fill -*-
<!-- -*- mode: auto-fill -*- -->

But these lines are not recognized as comments and are put into the generated HTML files.

Is there a way to write comments is the markdown file? Thanks.

2

Looks like there’s an answer here: syntax - Comments in Markdown - Stack Overflow

3

I tried the methods in this link, none of them works:

julia> using Markdown

julia> md = md"""
             [comment]: <> (comment 1)

             [//]: <> (comment 2)

             [//]: # (comment 3)

             <!-- comment 4 -->
             """;

julia> html(stdout, md)
<p>&#91;comment&#93;: &lt;&gt; &#40;comment 1&#41;</p>
<p>&#91;//&#93;: &lt;&gt; &#40;comment 2&#41;</p>
<p>&#91;//&#93;: # &#40;comment 3&#41;</p>
<p>&lt;&#33;– comment 4 –&gt;</p>

julia>
4

Are you using Documenter.jl? They have the syntax # hide to hide some forms of contents.

5

I think # leads a section title in markdown…

And # hide is only designated for use in a code/example block according to Syntax · Documenter.jl.

6

File-local variables should work with the following syntax according to the author of markdown-mode:

7

@Tamas_Papp

Thank you for replying , but I think you misunderstood what we are discussing.

We talking about the markdown format, as well as the Markdown module in the Julia stdlib. mostly the later one.

There’re many markdown tools that can convert markdown to HTML, including Julia’s Markdown module. Most of them support embedding comments in a certian syntax, like what was mentioned in the link @Mason provided.

But all these syntaxes don’t work with Julia’s Markdown module, I wonder if there’s a syntax work well with Julia’s Markdown module so that I can put some local variables into my md files. I tried the methods in the link you post, none of them works either (They set the local varables, but they are not comments to Julia’s Markdown module).

Also, I think this is not an offtopic thread…

8

Sorry for misunderstanding, I have put back the topic in Usage.

If you are generating docs using Documenter.jl, you may want to ask about comments in an issue there.

9

Never mind, I now created a directory local variable as a work-around:

$ cat .dir-locals.el
((markdown-mode
  (eval auto-fill-mode)))

But it will be better if the Markdown module supports comments in markdown text.

10

Please file an issue on GitHub then. Otherwise it’s unlikely that this will happen any time soon (not promising that it will if you do, of course :smiley: ).

11

it’s a natural suggestion but note that the Markdown module is not trivial, there’s a few open issues (OTOH treatment of lists over several lines and reflinks) that have been open for a long time.

In this particular case it would seem that adding a block similar to “Quotes” could do the trick (julia/block.jl at 0cd77ddd05a7c9d9c03a38d8e06bbddecb1ad908 · JuliaLang/julia · GitHub)

1 Like
12

Markdown: add ability to not escape html characters in markdown · Issue #35523 · JuliaLang/julia · GitHub, I think this one is fine to cope with the situation :sunny:

1 Like