Documentation from more than just 1 stylesheet

[gethinoakes]

Unsure if this can actually be done, as I can't see from the documentation. I have partial stylesheets that get included into the main style.scss, however if I put any mdcss documentation in these partials it doesn't show up in the outputted documentation.

It only works with mdcss comments inside the main style.scss

Thanks!

[stephenway]

@gethinoakes Could I see your configuration file?

[gethinoakes]

@stephenway I'm using PostCSS and Gulp,

require('mdcss')({
    title: 'StyleGuide',
    logo: 'logo.png',
    examples:  { css: ['../app/styles/style.css'] },
    assets: ['styleguide_assets/styleguide_logo.png', 'fonts'],
    destination: '../StyleGuide',
    theme: require('avalanchesass_mdcss_theme')
})

[stephenway]

Thanks @gethinoakes but could you provide the whole task? I just need to see how your src loading up the css files pattern wise.

[gethinoakes]

Sure,

gulp.task('sass', function () { //compile sass
    return gulp.src(sassFiles)
        .pipe($.sass().on('error', $.sass.logError))
        .pipe(postcss(processors, {syntax: scss}))
        // .pipe(cssnano({discardUnused: {fontFace: false}}))
        .pipe(gulp.dest(appFolder));
});

mdcss is part of the postcss 'processors' (the only other task in there is autoprefixer). I've also noticed that if I put styles in a subfolder of my styles folder then the StyleGuide gets generated but with no content at all, even if the main style.scss is in the parent folder.

Thanks for your help.

[stephenway]

Sorry I thought it would include your processors, need to see that as well because order matters. Thanks

[gethinoakes]

Ok hah hopefully this is everything? sassFiles = srcFolder + '**/*.scss'

processors = [
        autoprefixer({browsers: ['last 1 version', 'ie > 11', 'Safari > 7']}),
        rucksack(),
        require('mdcss')({
            title: 'StyleGuide',
            logo: 'logo.png',
            examples:  { css: ['../app/styles/style.css'] },
            assets: ['styleguide_assets/styleguide_logo.png', 'fonts'],
            destination: '../StyleGuide',
            theme: require('avalanchesass_mdcss_theme')
      })
    ]

gulp.task('sass', function () { //compile sass
    return gulp.src(sassFiles)
        .pipe($.sass().on('error', $.sass.logError))
        .pipe(postcss(processors, {syntax: scss}))
        .pipe(cssnano({discardUnused: {fontFace: false}}))
        .pipe(gulp.dest(appFolder));
});

rucksack currently isn't being used, and even if I take it out it doesn't make a difference.

[Yannicvanveen]

I'm running into the same issue. My Gulp task looks similar:

gulp.task('css', function() {

    return gulp.src('assets/scss/**/*.scss')
        .pipe(sass())
        .pipe(postcss([
            require('mdcss')({
                theme: require('mdcss-theme-test'),
                examples: {
                    css: ['https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css', '../assets/css/forms.css']
                }
            })
        ]))
        .pipe(gulp.dest('assets/css'));

});

I usually keep my components in separate .scss files that get imported by a main.scss file. I'd like to document these components in their own .scss file to keep things clear.

[gethinoakes]

I'm doing pretty much the same as @Yannicvanveen, I have different folders for different parts of my css which are all imported into style.scss.

There are two problems -

1. As soon as I added a folder beneath the main /styles folder it broke mdcss - the styleguide gets generated but there's no content just the header.
2. If all the styles are in the same folder and there's no sub-folders (v.messy) documentation is still only taken from style.scss

Any ideas @stephenway, @jonathantneal ? Thanks in advance... :)

[gethinoakes]

I've been investigating mdcss. The problem is that one it takes all the documentation comments from one stylesheet and then makes the whole styleguide index.html file from that. So then when it encounters another stylesheet with documentation it does the same thing, overwriting the previously generated styleguide.

Also I noticed the regex for detecting documentation no longer works.

Development seems to have stalled on mdcss, so I have forked it and will see how far I can get developing it further...

[stephenway]

We really don't test with Sass at the moment. I can vouch for plain CSS files using PostCSS as that is my main workflow. Maybe you could submit a PR? I know there are some issues that are outstanding right now, but I'm under heavy pressure to work on other things at the time being. Once I have more bandwidth I will be working towards a new release.

[gethinoakes]

That's strange, as I tried using plain CSS and had the same result. I have a few ideas on how to solve the issue, just don't know if their viable at the moment. I'm pretty new to all this PostCSS plugin development stuff - but my main task at work right now is to develop a StyleGuide so I'll be looking at this daily, anything I can do to improve mdcss I'll see about submitting a PR.

[stephenway]

Have you tried changing your gulp.src to just top level css files that import partials? (e.g. return gulp.src(['src/*.scss']))

[gethinoakes]

@stephenway yep, the last processed css file that contains documentation overwrites all previous css documentation files - seems to be because it regenerates the whole index.html from that last css file instead of just adding content.

I'm going to see if I can generate different parts of the template separately, and so that content is simply added on from file to file rather than being replaced.

[stephenway]

Interesting, I'm wondering how your forming your files though, is it one stylesheet importing partials with inline or md files linked?

[gethinoakes]

So if I have a main css file that imports other css files that contain documentation, the styleguide generates an empty template with just the layout left intact.

If I have multiple css files with documentation that don't import one another, mdcss only generates a the styleguide with content from the last css file it processed.

It doesn't matter if the markdown is imported or inline.

[gethinoakes]

Currently the css files are processed alphabetically and only documentation from the last one is used.

I am going to try and figure out how to take documentation from multiple css files, and if/when I've got that far I'll try and implement some sort of ordering system.

[gethinoakes]

@jonathantneal & @stephenway

I've hit an impasse with this. I've tried many different solutions, the closest I got was managing to get section titles from two different stylesheets into the one template file, but the content of these sections was all from the second stylesheet and also some of the sections were duplicated.

The underlying issue is that PostCSS returns a single array each time, I've tried but can't seem to collect each documentation object/array from separate stylesheets into one big array to then create complete documentation from.

Any help would be greatly appreciated.