grunt-styledoc
v0.0.3
Published
Grunt wrapper for styledoc: parser and showcase generator for JavaDoc-like comments in CSS, LESS, SASS etc.
Downloads
8
Maintainers
Readme
grunt-styledoc
Grunt wrapper for styledoc: parser and showcase generator for JavaDoc-like comments in CSS, LESS, SASS etc.
Getting Started
This plugin requires Grunt ~0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-styledoc --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-styledoc');
The "styledoc" task
Overview
In your project's Gruntfile, add a section named styledoc
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
styledoc: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
});
Options
options.templates_dir
Type: String
Default value: "<module_dir>/templates/"
Path to templates directory, relative to current location.
options.template
Type: String
Default value: "default"
Name of showcase page template.
options.language
Type: String
Default value: "en"
Language to apply when creating page (should exist in template's languages
directory)
options.doctype
Type: String
Default value: "html5"
Live preview target doctype (should exist in template's preview
directory).
options.page_title
Type: String
Default value: ""
Main title of document.
options.css_url_http
Type: Sumber
Default value: undefined
HTTP(S) path to CSS file to use in live preview (detected automatically by default).
options.iframe_delay
Type: Number
Default value: 2000
Delay (ms) before refreshing iframe height.
This delay is needed to render preview item iframe page, measure its height, and then apply this height to <iframe>
element itself.
Not needed if PhantomJS is used.
options.use_phantomjs
Type: Boolean
Default value: false
Use PhantomJS to pre-measure and pre-set preview iframes height values (so iframe delay is not needed). Requires PhantomJS to be installed in system.
options.phantomjs_viewport
Type: Object
Default value: { width: 1280, height: 800 }
Viewport size for PhantomJS instances.
options.silent_mode
Type: Boolean
Default value: false
Disable console messages.
options.preview_padding
Type: Number | Number[]
Default value: undefined
Padding value(s) for preview container. Useful if elements have box-shadow
, outline
or similar styles that don't affect the container offset size.
Value can be a number (4 => padding: 4px
) or array of numbers ([ 4, 3, 8 ] => padding: 4px 3px 8px
).
options.background_color
Type: String
Default value: undefined
Background color CSS value for both main showcase page and iframe preview pages (for seemless iframes).
Use this option if your target body color differs from value proposed by template (#fff
for default
template, #000
for dark
template, etc.).
Value should be a string containing any CSS-valid color value (e.g. "#f1f1f1"
, "darkgray"
, or even "rgb(17, 17, 36)"
).
Usage examples
Basic usage
In this example, only page_title
option is provided. Although this option isn't required, showcase page just look poor without a title :)
grunt.initConfig({
styledoc: {
options: {
page_title: "My styles presentation"
},
files: [
{ src: "path/to/your.css", dest: "path/to/output/directory/" }
],
},
});
Extented configuration
In this example, all available options are added.
grunt.initConfig({
styledoc: {
options: {
page_title: "My styles presentation",
templates_dir: "my/custom/templates/dir/",
template: "my_custom_template",
language: "ru",
doctype: "xhtml10_transitional",
iframe_delay: 3000, // actually ignored if PhantomJS is enabled and installed
use_phantomjs: true,
phantomjs_viewport: { width: 640, height: 480 },
silent_mode: true,
preview_padding: [ 15 10 20 12 ],
background_color: "#ffc"
},
files: [
{ src: "path/to/your.css", dest: "path/to/output/directory/" }
],
},
});
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Version history
- 0.0.3 (2015-05-12): Upgrade to
styledoc 0.0.8
- 0.0.2 (2014-12-01): Upgrade to
styledoc 0.0.6
- 0.0.1 (2014-11-30): Initial release