@import/@include statements cause parsing error when content is within @description and a ``` section.

[farias-r7]

Just wanted to start by saying awesome work on documentcss!

Problem:

DocumentCss tries to parse any "tags" that are within the @description tag. This makes it hard to properly document usage of the scss file. Here is an example:

/**
  *
  * @stylesheet _icons.scss Icons
  * @parent styles
  *
  *
  * @description
  * This icon page is being pulled from documentation in the '_icons.scss'
  *
  * 
  *
  *
  * @demo demos/modules/icons/demo.html
  *
  * ### Sample Rule Creation with mixins available in the icons scss file
  *
  * **Note due to a parsing bug in documentCSS assume (@) is just @
  * 
  * ``` 
    // Font face definitions cannot be nested in a class
    (@)include r7-icon-font-face('/fonts');

    // Sample Light Theme Usage
    (@)import 'modules/buttons/light-theme';
    (@)import 'modules/icons/light-theme';

    .ui-light{
      (@)include r7-buttons();
      (@)include r7-icons();
    }

    //Sample Dark Theme Usage
    (@)import 'modules/buttons/dark-theme';
    (@)import 'modules/icons/dark-theme';

    .ui-dark{
      (@)include r7-buttons();
      (@)include r7-icons();

      // Example font size change
      &.large{
        (@)include r7-icon-font-size(1.9rem);
      }
    }

  * ```
  *
**/

When trying to build the docs and I replace (@) with @ in the above example, I get:

Generating styles at styleguide
>> WARNING!!
>> There is no @include tag. did you mean @class ?

[tomgreever]

You can prefix these with two @@ and it will solve this. :)

Example:

// Font face definitions cannot be nested in a class
    @@include r7-icon-font-face('/fonts');

Will generate:

// Font face definitions cannot be nested in a class
    @include r7-icon-font-face('/fonts');

[farias-r7]

Awesome! Thanks for the quick reply. Sorry if I missed this in the docs! I'll close the issue.

[tomgreever]

No problem. It is documented somewhere in the official docs on DocumentJS.com but because it's a common issue for style guides we also added it to the bottom of this FAQ: http://documentcss.com/faq.html

[farias-r7]

@tomgreever. I didn't want to open a new issue since it's somewhat related to tags.

According to http://documentcss.com/docs/lsg-quickstart-creating-page.html

When you're writing with DocumentJS, you'll use tags. These are @-prefixed and tell DocumentJS to do something specific.

Should http://documentjs.com/docs/documentjs.tags also work when we document scss files with doucmentCSS?

I ask since I'm thinking of documenting scss mixins and functions. The documentJS markup looks a lot cleaner than me trying to write up docs within my @description tag for these mixins/functions.

[tomgreever]

Yes, all the features of DocumentJS should work. The engine itself is not aware of the type of file its processing. It just looks for the comments. So it doesn't matter if it's SCSS or any other file type.

I'd be interesting in hearing what type of tags you want to add and what that looks like. Perhaps it's something worth adding to the project as a whole.

Also, you can write straight markdown. It does not have to be within @description. Anything inside the comment block, even regular HTML, will be generated on the page.

[tomgreever]

Email me at tom@bitovi.com if you want to talk further. I'd be interested in seeing how you're using it. We are working on a rewrite and maybe there are some things we can do better in the next version.