DocumentCSS Starter Kit
DocumentCSS is an awesome way to document style patterns as you make them. This starter kit was built to make it super easy to get started.
Speaking of getting started...
- Clone this repo.
- Transfer the contents into your own style guide repo. You'll want to update stuff in the
package.jsonfile to reference your style guide repo.
- Install gulp globally if you never have:
npm install -g gulp
- Optionally you can install documentjs globally so you can run the
npm install -g documentjs.
gulp dev to compile the style guide and run a live reloading local server at
http://localhost:4200/. You can change the port number in
- This was built to use LESS, but you could use SASS/SCSS if you edit the references to
- LESS is compiled with autoprefixer and minify.
- When editing the style guide template files, don't spam save! It takes about 5s or so to fully recompile.
- Live reload injects some js into the site that might show up as a js tab on your style demos (next to the "demo" and "HTML" tabs). This js tab won't appear in the site when live reload isn't running.
How this is structured.
The strategy here is that your core styles patterns are in their own repo with a style guide that others can reference. Then these styles are imported into your apps (the compiled styles from the
dist folder), you'll have additional app view specific styles that don't necessarily cut it as a pattern in the app's own repo. If you develop a repeatable pattern in an app, transfer it to the style guide! You'll be able to document it quickly and easily.
npm install and run
gulp dev for the first time, you'll have a folder structure like this.
- dist - where your compiled and autoprefixed styles will go.
- less - where your styles files and demo snippets go. Note that the
styles.lessfile is your LESS import file that gulp will compile (if you change this files name, update the reference in
- demos - where your demo snippets go for style guide examples.
- style-guide-theme - where you modify styles and templates that apply to the style guide itself. Remember that when saving changes here, it takes about 5s to recompile everything, don't spam save!
- styleguide - where your pattern library is generated.
How to do stuff.
Documenting styles as you go.
If you checkout the
buttons.less example file in the
less folder, you can get an idea how it works.
- At the top of the document an
@stylesheet NAME TITLEis declared. This creates a page.
NAMEis the unique name that will show up in the URL,
TITLEis what will appear in the style guide as the page header.
@parent NAME ORDERtells the static site generator where to place this page in the navigation. In this starter kit, you'll pretty much always have this as
@parent styleguideplus whatever index number you want to give it, controlling what order it appears in.
@descriptioncan be written using markdown and appears at the top of the page under the main title.
You can also use
@group and other cool stuff to organize your documentation. Learn more at documentcss.com.
Individual Style Demos
- Above where a pattern's styles are written, declare
@styles NAME TITLEto document it. The
NAMEis the unique identifier that shows up in the URL, and the
TITLEappears on the page.
@descriptionallows you to write markdown that will appear below the
@demo PATHallows you specify a demo snippet to use with these styles. Create a demo snippet of
./less/demos/and reference it in the styles file (ex.
Customizing the Style Guide
- Do so in
staticfolder contains styles and images that you can override. The styles in there are written with LESS, they're essentially copied from the default documentjs theme with a few modifications.
templatesfolder contains handlebar templates that you can modify for changing the header/footer/pages/sidebar markup.
styleguide folder is your generated pattern library. You can upload that to any server or use github pages to host it.