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;
}
Usage
Add mdcss to your build tool:
npm install mdcss --save-devNode
require('mdcss').process(YOUR_CSS, { /* options */ });PostCSS
Add PostCSS to your build tool:
npm install postcss --save-devLoad mdcss as a PostCSS plugin:
postcss([
require('mdcss')({ /* options */ })
]);Gulp
Add Gulp PostCSS to your build tool:
npm install gulp-postcss --save-devEnable 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-devEnable 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'll want to use
either a <code><button></code> or an <code><a></code> element:</p>
<pre><code class="lang-html"><button class="btn">Click</button>
<a class="btn" href="/some-page">Some Page</a>
</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
Commentnode 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.