CoffeeScript comments and Markdown

[Prevole]

Hi,

I have some problem with the Markdown syntax and the CoffeeScript comments syntax.

When I have something like that:

###
## My Title
###

It will generate a H2 tag correctly rendered but when I do something like this:

###
### My Title
###

I have a syntax error in my editor and the generation of the doc is not possible.

In this tool: https://npmjs.org/package/coffeedoc They address the problem by offering the possibility to escape the # comments like that \#\#\#. As the author said, it is ugly but it works and should be a workaround.

Or maybe there is already a solution that I missed?

[Prevole]

I currently have a workaround to write my titles with Markdown in my CoffeeScripts comments.

# ### My title in H3
###
My Block Comments
###

This works but it does not generate exactly the documentation that will normaly be done when you set the title inside the block comment. It generates the title, a line and the block comment.

[mlangenberg]

Auch, just got bit by the same feature. Just as I thought I was done writing API docs.

[switz]

+1

[forivall]

+1

[alinex]

To overcome this problem I introduced the following syntax in my code tool:

###
#3 Heading level 3
###

The reader will transform this to the correct markdown befor transmormation. The same also goes for headings level 4-6.

The code therefore looks like:

text = text.replace /(\n\s*)#([1-6])(\s+)/, (_, pre, num, post) ->
  "#{pre}#{util.string.repeat '#', num}#{post}"

Maybe a similiar replacement can be added to docker, too.