Warn on (ignored) HTML comments in markdown
har7an opened this issue · comments
Hello,
this is a feature request asking that HTML comments found in markdown files (such as <!-- ... -->) be recognized by Documenter, maybe printing a warning in the build log?
The background I'm asking for this is that I was astonished to find that commenting out sections of a "broken" WIP documentation file has no effect on the resulting output. I'm aware that this is related to #517 (and e.g. #1409) and I understand that this is fundamentally an upstream issue. But it appears that this has been an upstream issue for more than 6 years by now.
From a users perspective this is frustrating. Today I drafted a documentation file in markdown and upon building got a lot of errors due to broken refs back. At this point I wanted to comment out all of the content and start adding individual snippets bit-by-bit to find what worked and what didn't. Since the comments are ignored, this had no effect on the output. My workaround in the end was to keep a temporary, unnamed buffer (nvim) open next to the markdown file I was actually editing, manually cutting and pasting contents over. It's not exactly an ideal experience.
Had Documenter told me that it doesn't support comments in Markdown from the beginning, this would have at least saved me quite a bit of "debugging".
The workaround is to enclose it in @raw comment block
```@raw comment
Comment text
```
But indeed, this in an upstream issue. Julia "Markdown" is only a subset of markdown, and unfortunately, inline-HTML is one of the many things it does not support (#517). The most likely solution is for Documenter to switch to another Markdown parser at some ponit, e.g., CommonMark.jl, at least for reading .md files, see also #1373 (comment)
I'm going to close this as a duplicate of the existing issues, but we're aware of this problem.