Feature request: Markdown files?

[phun-ky]

First of all, great package! Work like a charm!

However, there is a feature I really miss, and that is to be able to use markdown files for the documentation. This because the inline documentation with comments in the css files (or stylus/less what not) can be quite tedious to maintain, remembering to use the * and the correct indendation and no autocomplete/syntax highlightning in the comments. This feature would also allow the files to be more editable by github users (for those projects using it)

I would love to have something like this:

/**
 * @section Buttons
 * @doc Components.Buttons.md
 * @sectionof Components
 */

The *.md file can contain examples and code.

Is this doable and within the scope of this module?

[straker]

I'm a bit unfamiliar with separate markdown documentation. I know Styledown has the option to. Is that along the lines you were thinking?

I guessing to implement it we would need some sort of tag parsing for the .md file just like we have for the inline .css comments. I can take a look around to see if anyone has already created something like that.

[phun-ky]

Yeah, Styledown has a nice approach to this. The *.md-file feature is not a deal-breaker for us to use livingcss, but would ease the documentation management pain

[straker]

So looking over Styledown's docs, it seems they use the md files to generate sections via headings, subsections using nested headings, section descriptions, and examples. They use one file to do all of that though.

Could you provide an example of the documentation management pain you're feeling? Maybe a detailed example on how the @doc rule would solve it? That should help me fully understand the problem and make sure we solve it.

[phun-ky]

@straker I just sent you an email with an example

[straker]

Amazing. I never would have thought to do it that way. Ya, an @doc would make that much easier. So it looks like if the separate file allowed you to write the description block of a section that would ease 90% of your pain. I'm not sure how easy it would be to get code and examples as well into the doc file, but I'll see what I can do.

[straker]

Released in 4.3.0

[phun-ky]

Nice! Good work!

Trying it out now, but I ran into an issue. Where is the *.md-files ment to be located? I have n+1 repositories containing stylus files (components). These components are installed into a "styleguide" repo that is the styleguide itself. I use gulp-livingcss and I include the styles files per module like so:

return gulp.src([
  './node_modules/<a module>/src/<a module>.styl',
  './node_modules/<b module>/src/<b module>.styl',
  ...
 });

I want the *.md-files per module reside in the component (the components repo/module) root, /docs/*.md respectively:

'./node_modules/<b module>/docs/introduction.md',

So I can generate the component doc both separately , and together in the "styleguide" repo.

To clarify, I have this in styleguilde repo/gulpfile.js:

return gulp.src([
  './node_modules/<a module>/src/<a module>.styl',
  './node_modules/<b module>/src/<b module>.styl',
  ...
 });

And In <a module>.styl I have:

/**
 * @doc introduction.md
 * @section
 */

introduction.md is located here:

'./node_modules/<a module>/docs/introduction.md',

Is the easiest way to copy the markdown files? If so, where?

Further, with the latest version, I get this error:

(node:32702) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error in plugin 'gulp-livingcss'
Message:
  unnamed section (/workspace/styleguide/node_modules/<a module>/src/<a module>.styl:21)

It says unnamed section, but according to the docs, the title should be the section?

This is the markdown file I am currently testing with:

# This is an introduction

Lorum ipsum dolor sit amet This markdown file can define the `@section` name using a heading and the section description. Anything that is not an `@example` or `@code` code block will be added to the description of the section.

```
This code block will be part of the description.
```

```html
@example
<p>This code block will be treated as the <code>@example</code> tag</p>
```

[straker]

The doc files are referenced by relative path from the parsed file, so for your example it would be

/**
 * @doc ../docs/introduction.md
 * @section
 */

I tested your markdown doc example and didn't get an error thrown on my end, so I'm not sure what's going on there.

If you're using introduction.md as the doc path, which is located in the docs directory, then you should have gotten a File not found error since there wouldn't be a file called introduction.md as a sibling to the <a module>.styl file.

[phun-ky]

Any progress here? I still can't get the @doc tag to work

EDIT:

And I still get no error from livingcss/gulp-livingcss:

gulp.task('livingcss',() => {
  return gulp.src([
    './node_modules/wax-core/src/wax-core.styl',
    './node_modules/wax-typography/src/wax-typography.styl'
  ])
    .pipe(livingcss('bin',{
      template: './template/template.hbs',
      preprocess: (context, template, Handlebars) => {
        // register a glob of partials with Handlebars
        return livingcss.utils.readFileGlobs('./template/partials/*.hbs', function(data, file) {

          // make the name of the partial the name of the file
          var partialName = path.basename(file, path.extname(file));
          Handlebars.registerPartial(partialName, data);
        });
      }}))
    .on('error',err => {
      console.log(err);
    })
    .pipe(gulp.dest('bin'));
});

[phun-ky]

Hm, if I go into the wax-core project and use a gulp-livingcss-task there, I get the warning and also the @doc tag works after tweaks from the warning. Weird.

[phun-ky]

If my assumption is correct, the doc referred to with the @doc-tag is supposed to be relative to the stylus file parsed, not the gulpfile.. 🤦‍♂️

Edit: I now get this error:

{ [Error: unnamed section (/home/projectFolder/wax-styleguide/node_modules/wax-core/src/wax-core.styl:290)]
  message: 'unnamed section (/home/projectFolder/wax-styleguide/node_modules/wax-core/src/wax-core.styl:290)',
  showStack: false,
  showProperties: true,
  plugin: 'gulp-livingcss',
  __safety: { toString: [Function: bound ] } }

With this syntax:

/**
 * @doc ../docs/blue-light-filtering.md
 * @section
 * @sectionof Usability.Accessibility
 */

Edit:

Forced upgrade of dependencies and it seems to work... #rookiemistake #facepalm #rubberduck...

[straker]

Glad you got it working. Is the feature meeting your needs?

[phun-ky]

@straker yes! Sorry for the huge load of comments here 🤦‍♂️ and thanks for the feature!