does not work with Sass syntax comments

[VinSpee]

given the following comment:

/*
 * Headings
 * ==========
 *
 * Headings examples ranging from H1-H4.
 *
 *  <h1>Heading 1</h1>
 *  <h2>Heading 2</h2>
 *  <h3>Heading 3</h3>
 *  <h4>Heading 4</h4>
 */

I expect the output to be

Headings

Headings examples ranging from H1-H4.

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>

Instead, the output is:

• Headings
• ========== *
• Headings examples ranging from H1-H4. *

• Heading 1

• Heading 2

• Heading 3

• Heading 4

The rendered HTML:

<div class="comment">
  <ul>
    <li>Headings</li>
    <li>==========*</li>
    <li>Headings examples ranging from H1-H4.*</li>
    <li>&lt;h1&gt;Heading 1&lt;/h1&gt;</li>
    <li>&lt;h2&gt;Heading 2&lt;/h2&gt;</li>
    <li>&lt;h3&gt;Heading 3&lt;/h3&gt;</li>
    <li>&lt;h4&gt;Heading 4&lt;/h4&gt;</li>
  </ul>
</div>

any thoughts on how to remedy this?

[winstromming]

Sassdown was constructed to parse Markdown syntax and the rendered output you are experiencing is therefore entirely correct (* with newline in Markdown is a list item). There are many ways to write comments in SCSS files, but Markdown syntax is pretty explicit.

[VinSpee]

I understand that is markdown's syntax. With that being the case, there should be some way to parse .sass comments, be it the // format or whatever.

On Tue, Nov 5, 2013 at 3:44 PM, Jesper Hills notifications@github.com
wrote:

Sassdown was constructed to parse Markdown syntax and the rendered output you are experiencing is therefore entirely correct (* with newline in Markdown is a list item). There are many ways to write comments in SCSS files, but Markdown syntax is pretty explicit.

Reply to this email directly or view it on GitHub:
#12 (comment)

[winstromming]

I understand that is markdown's syntax. With that being the case, there should be some way to parse .sass comments, be it the // format or whatever.

Respectfully, Sass + Markdown was the whole purpose of Sassdown. // are reserved for actual inline comments in the code. Your issue could be circumvented by applying strict rules on comment syntax, much like KSS, like so:

/*
 * title: Headings
 * section: Typography
 * text: Here are my headings
 * html:
 *         <h1>Heading One</h1>
 *         etc
*/

But again, that isn't Markdown. It's too strict and doesn't read like natural language. There are other living styleguide generating plugins that you could use if you require that amount of control over your comment syntax. Sassdown was created to be used with Handlebars/Markdown and I'm sticking to that.

[VinSpee]

I think you may be misunderstanding me. I totally understand that. My question is regarding .sass, the indented syntax. I'm just trying to figure out if Sassdown is compatible at all.

if the required comment syntax is

/*

your comment
===========
*/

then this is not compatible with sass's indented syntax, as sass's indented syntax allows for

// your comment

or the banner syntax with a space in front of each line after the first

/*
 your comment
 ===========
 */

It would be nice to offer compatibility with either syntax.

[winstromming]

Sorry, it does seem I misunderstood you. Your pasted comment in the first post included an asterisk on each line. At first, I assumed this would never work. But I've thought about this for a couple of days and we can leverage logical operators within Regex to accomplish this anyway. First, let us go through the various styles of comments we want to parse.

Possible commenting syntax styles

Each of these are possible and valid. Each must successfully parse via Markdown into identical HTML.

Left-aligned, unspaced

/*
Navigation
==========
Tight example.
    <span class="btn">Test</span>
*/

Left-aligned, spaced

/*

Navigation
==========

Spacious example.

    <span class="btn">Test</span>

*/

Indented

/*

 Navigation
 ==========

 One-space indented example.

     <span class="btn">Test</span>

*/

Asterisk-indented

/*
 * Navigation
 * ==========
 * 
 * Sass asterisk-delimited indented example.
 *
 *     <span class="btn">Test</span>
 *
 */

Asterisk-indented, unspaced

/*
 *Navigation
 *==========
 *Sass tight asterisk-delimited indented example.
 *    <span class="btn">Test</span>
 */

PS. I am not going to include inline // comments as these are explicitly ignore even by SASS into final output. Sassdown will only search for and parse block comments into Markdown.

[winstromming]

@VinSpee Can you please update your package.json Sassdown dependency version to 0.1.0 and attempt a build again. Latest published npm release should allow for exactly the comment syntax you require.

[VinSpee]

seems to be working aside from newlines inside of code fences. How should we treat them?

Ex:

/*
 * ````
 * <h1>Heading 1</h1>
 * <h2>Heading 2</h2>
 * <h3>Heading 3</h3>
 * <h4>Heading 4</h4>
 * ````
 */

is compiling as

<h1>Heading 1</h1> <h2>Heading 2</h2> <h3>Heading 3</h3> <h4>Heading 4</h4>

rather than

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>

[winstromming]

Code fences should also be parsed. I've made the necessary modifications to allow for code-fenced blocks to be rendered into identical HTML now. See 3970ec6 for possible source syntax support.

To clarify: fenced code blocks are now supported within any of the above styles of comment syntax

Finally, commit 4e874dd has also enabled GitHub Flavoured Markdown to be matched and rendered instead if found, without requiring external options. Closing #6.

@VinSpee grab Sassdown version 0.1.1

[VinSpee]

Looks like the source/example feature isn't working:

/*
 * Headings
 * ==========
 *
 * Headings examples ranging from H1-H4.
 *
 *````
 *<h1>Heading 1</h1>
 *<h2>Heading 2</h2>
 *<h3>Heading 3</h3>
 *<h4>Heading 4</h4>
 *````
 */

only results in the code being show, not an example as well.

output:

<div class="comment"><h1>Headings</h1>

<p>Headings examples ranging from H1-H4.</p>

<p><code>
&lt;h1&gt;Heading 1&lt;/h1&gt;
&lt;h2&gt;Heading 2&lt;/h2&gt;
&lt;h3&gt;Heading 3&lt;/h3&gt;
&lt;h4&gt;Heading 4&lt;/h4&gt;
</code></p></div>

edit;

DOH. My bad. Seems to be clear.

[winstromming]

Confirm that's all good your end now? In your example above you have used four fences rather than three by the way. Just tested both of the following and either worked fine:

/*
 * Headings
 * ==========
 *
 * Headings examples ranging from H1-H4.
 *
 *```
 *<h1>Heading 1</h1>
 *<h2>Heading 2</h2>
 *<h3>Heading 3</h3>
 *<h4>Heading 4</h4>
 *```
 */

/*
 * Headings
 * ==========
 *
 * Headings examples ranging from H1-H4.
 *
 * ```
 * <h1>Heading 1</h1>
 * <h2>Heading 2</h2>
 * <h3>Heading 3</h3>
 * <h4>Heading 4</h4>
 * ```
 */