nuǝɯ pǝɥsᴉꞁod mǝu

    mdcss

    1.5.2 • Public • Published

    mdcss

    NPM Version Build Status

    mdcss lets you easily create and maintain style guides with CSS comments using Markdown.

    /*---
    title:   Buttons
    section: Base CSS
    ---
    
    Button styles can be applied to any element. Typically you'll want to use
    either a `<button>` or an `<a>` element:
    
    ```example:html
    <button class="btn">Click</button>
    <a class="btn" href="/some-page">Some Page</a>
    ```
    */
    
    .btn {
    	background-color: black;
    	color: white;
    }
    

    screenshot

    Usage

    Add mdcss to your build tool:

    npm install mdcss --save-dev

    Node

    require('mdcss').process(YOUR_CSS, { /* options */ });

    PostCSS

    Add PostCSS to your build tool:

    npm install postcss --save-dev

    Load mdcss as a PostCSS plugin:

    postcss([
        require('mdcss')({ /* options */ })
    ]);

    Gulp

    Add Gulp PostCSS to your build tool:

    npm install gulp-postcss --save-dev

    Enable mdcss within your Gulpfile:

    var postcss = require('gulp-postcss');
     
    gulp.task('css', function () {
        return gulp.src('./css/src/*.css').pipe(
            postcss([
                require('mdcss')({ /* options */ })
            ])
        ).pipe(
            gulp.dest('./css')
        );
    });

    Grunt

    Add Grunt PostCSS to your build tool:

    npm install grunt-postcss --save-dev

    Enable mdcss within your Gruntfile:

    grunt.loadNpmTasks('grunt-postcss');
     
    grunt.initConfig({
        postcss: {
            options: {
                processors: [
                    require('mdcss')({ /* options */ })
                ]
            },
            dist: {
                src: 'css/*.css'
            }
        }
    });

    Options

    theme

    Type: NPM Repository
    Default: require('mdcss-theme-github')

    The theme used by mdcss to create the style guide.

    require('mdcss')({
        theme: require('mdcss-theme-github')
    })

    Theme-specific options may also be passed in from the theme module itself, but note that any global options would then be ignored.

    require('mdcss')({
        theme: require('mdcss-theme-github')(/* options */)
    })

    destination

    Type: String
    Default: 'styleguide'

    The directory to write the style guide to.

    assets

    Type: Array
    Default: []

    The list of files or directories to copy into the style guide directory.

    index

    Type: String
    Default: 'index.html'

    The file to write the style guide to.

    Writing documentation

    To add a section of documentation, write a CSS comment that starts with three dashes ---.

    /*---
     
    This is documentation.
     
    */
    /*
     
    This is not documentation
     
    */

    The contents of a section of documentation are parsed by Markdown and turned into HTML.

    /*---
     
    Button styles can be applied to **any** element. Typically you'll want to use
    either a `<button>` or an `<a>` element:
     
    ​```html
    <button class="btn">Click</button>
    <a class="btn" href="/some-page">Some Page</a>
    ​```
     
    */
    <p>Button styles can be applied to <strong>any</strong> element. Typically you&#39;ll want to use
    either a <code>&lt;button&gt;</code> or an <code>&lt;a&gt;</code> element:</p>
     
    <pre><code class="lang-html">&lt;button class=&quot;btn&quot;&gt;Click&lt;/button&gt;
    &lt;a class=&quot;btn&quot; href=&quot;/some-page&quot;&gt;Some Page&lt;/a&gt;
    </code></pre>

    The contents of a section may also be imported from another file.

    buttons.md:

    Button styles can be applied to **any** element. Typically you'll want to use
    either a `<button>` or an `<a>` element:
    
    ```html
    <button class="btn">Click</button>
    <a class="btn" href="/some-page">Some Page</a>
    ​```
    

    base.css:

    /*---
    title:  Buttons
    import: buttons.md
    ---*/

    The contents of a section may be automatically imported as well. For example, had the import been omitted, a sibling file of base.buttons.md or base.md would have been used (in that order of preference) if they existed.

    Details

    Additional heading details are added before a second set of three dashes --- in a section. These heading details are parsed and added to the documentation object.

    /*---
    title:   Buttons
    section: Base CSS
    ---
     
    Button styles can be applied to **any** element.
     
    */
    {
        "title": "Buttons",
        "section": "Base CSS",
        "content": "<p>Button styles can be applied to <strong>any</strong> element.</p>"
    }

    Writing themes

    Creating themes requires an understanding of creating and publishing npm packages.

    The easiest way to create a new theme is to visit the boilerplate theme project page, fork and clone it, and then run npm install.

    To create a theme from scratch; create an index.js like this one in a new npm package directory:

    module.exports = function (themeopts) {
        // initialize the theme
        // example usage:
        // 
        // require('mdcss')({
        //   theme: require('mdcss-theme-mytheme')({ /* opts */ })
        // })
     
        // return the theme processor
        return function (docs) {
            // do things with the documentation object
            // remember to use __dirname to target this theme directory
     
            // return a promise
            return new Promise(function (resolve, reject) {
                // resolve an object with an assets path and a compiled template
                resolve({
                    assets:   '', // directory of files to copy
                    template: '' // contents of style guide to write
                });
            });
        };
    };
     
    // this is so mdcss can check whether the plugin has already been initialized
    module.exports.type = 'mdcss-theme';

    The exports function is where theme options are initialized.

    require('mdcss')({
        theme: require('mdcss-theme-mytheme')({ /* theme options */ });
    });

    The exports function returns a theme processor. The theme processor is what receives the ordered list of all the parsed documentation objects as well as the options originally passed into the mdcss plugin.

    Documentation object

    Each documentation object may contain the following properties:

    • title: The title of the current section of documentation.
    • name: A unique, hash-safe name of the current section of documentation.
    • section: The proper title of a parent section.
    • content: The body copy of the current section of documentation.
    • parent: The parent section.
    • children: An array of child sections.
    • context: The original Comment node used to generate the current section of documentation.
    • import: A path to the file representing the content of the current section of documentation.

    In addition to these properties, a documentation object includes any additional details.

    /*---
    title:      Buttons
    section:    Base CSS
    yakkityyak: Don’t Talk Back
    ---
     
    Button styles can be applied to **any** element.
     
    */

    Have fun, and thanks for using mdcss.

    Install

    npm i mdcss

    DownloadsWeekly Downloads

    178

    Version

    1.5.2

    License

    CC0-1.0

    Last publish

    Collaborators

    • stephenway