Feature request: Markdown files? about livingcss HOT 13 CLOSED

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

from livingcss.

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.

from livingcss.

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

from livingcss.

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.

from livingcss.

@straker I just sent you an email with an example

from livingcss.

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.

from livingcss.

Released in 4.3.0

from livingcss.

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>
```

from livingcss.

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.

from livingcss.

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'));
});

from livingcss.

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.

from livingcss.

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...

from livingcss.

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

from livingcss.