styledown/styledown

Markdown-based styleguide generator

Styledown

Write maintainable CSS styleguides efficiently using a Markdown. See example ▸

Installation

$ npm install -g styledown
$ styledown --help

How it works

Styledown is made to work in most web development setups. It doesn't favor any framework or language or any preprocessor.

• Document your CSS files with inline comments, or as a separate .md file.
• Create a file with styleguide configuration.
• Invoke styledown *.css > styleguide.html.
• Enjoy your styleguide! Read more about the format.

Quickstart guide

Here's a generic guide on getting started with Styledown on any project. We're gonna assume that you're using Sass and that your project bundles all CSS files into one file.

Let's assume that your files are in css/, and that your final styleguide will be in public/styleguide.html.

                    Example setup

.----------------------.     .---------------------.
| css/                 |     |                     |
|     config.md        |     |  public/            |
|     button.scss      | ==> |    styleguide.html  |
|     forms.scss       |     |                     |
|     whatever.scss    |     |                     |
'----------------------'     '---------------------'

Step 1: Document

Document your project's stylesheets with inline comments, or as separate .md files.

/**
 * Component name:
 * `.your-component-here` - documentation on what your
 * component is goes here. Markdown is encouraged.
 *
 *     @example
 *     div.your-component-here
 *       h3 Sample code
 *       p goes here
 */

.your-component-here {
  display: block;
  ...
}

Read more: Documenting ▸

Step 2: Configure

Make a file, let's call it config.md. (styledown --conf > config.md) This lets you define what will be in the output head/body.

# Styleguide options

### Head

    link(rel="stylesheet" href="/assets/application.css")
    link(rel='stylesheet' href='https://cdn.rawgit.com/styledown/styledown/v1.0.2/data/styledown.css')
    script(src='https://cdn.rawgit.com/styledown/styledown/v1.0.2/data/styledown.js')

### Body

    h1 My Awesome Styleguides
    div#styleguides(sg-content)

The first one (application.css) should point to your project's concatenated stylesheets. The second and third one (styledown.css and styledown.js) point to the default Styledown CSS/JS files.

Read more: Configuration ▸

Step 3: Build

Invoke styledown to generate an HTML file. (Make sure that the extras.css is passed on the end, since anything after the "Styleguide options" heading is ignored.)

$ styledown css/*.css css/config.md > public/styleguides.html

Enjoy!

Now open public/styleguides.html in your browser.

Usage

Styledown generates .html styleguides. It can take CSS files or Markdown files, or a combination of the two.

Inline CSS mode: Parses comments from CSS files. This is what happens when you pass .css, .sass, .scss, .less and .styl files.

$ styledown *.css > styleguide.html

Markdown mode: Takes Markdown files.

$ styledown *.md > styleguide.html

Markup format

Read more: Markup format ▸

©️

Styledown © 2013+, Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors.

ricostacruz.com  ·  GitHub @rstacruz  ·  Twitter @rstacruz

styledown's Issues

Markdown config not working as expected for HTML inline comments

I get this from using the config.md and writing my inline guides in HTML as shown from my editor here: . The problem is the markdown isn't playing fine with the html coming in by not creating the Head and Body as expected.

Then I tried to generate a html config with:

styledown --conf > config.html

but that still generated a markdown in html producing the exact same result. I don't want to deal with the indentation struggle of jade. My first attempt at it just produced it all as a single line text.

How can my HTML work with the config?

Using comments, strange 'closing bracket' appears

I'm using comments to generate styledown. Below is my code

and the output with strange /}

Option to display CSS code in output

I would like to include css code along with the example source code. This way one could not only see the html source for the example but also the css that belongs to it.

I saw that you added some classes to the @example tags with simply add classes to the html output.
If I would implement this is as an option, would you recommend adding it to the the example tags, or would you prefer a different method.

I would recommend using it mainly for the inline style, because then we could assume, that the css for specific elements come come after an example block.

Css components order

Hi!
Thanks for your job, it's a very fast and easy solution to setup a styleguide into a webproject.

I would like to know if it's possible to sort css/scss components in the way we want ? Apparently, it seems to take the files in an alphabetical way if i'm right.

Thanks !

Space after inline elements removed

This applies to the parsed markdown throughout and jade/html/jade:markdown examples.

So in the .sg-text, after any inline element (like code, em, strong, a, etc.) there is no space between it and the next word.

Also if there's an inline element in an example, i.e.:

    @example
    p This is an #[em emphasized] element

Returns a weird code example, with no space after the inline element (in this case em):

<p>This is an
    <em>emphasized</em>element
    </p>

Expected:

<p>This is an <em>emphasized</em> element</p>

Jade has been deprecated, upgrade to Pug?

The Jade project has been renamed to Pug. Jade is no longer maintained.

Navigation feature

Hi,
It's not an issue but a feature request.
Are you going to develop a navigation through all the styleguides components ?
Like an aside navbar with link pointing to an anchor :)

In a more general way, are you going to devellop/maintain new features in the future ?

Thanks

can't run syledown

i installed it globally, but running styledown --help
throws -bash: styledown: command not found

Styledown.parse([Array]) fails to process CSS files that come after the first .md filej.

var files = [
  { name: 'app.less', data: '...' },
  { name: 'config.md', data: '...' },
  { name: 'link.less', data: '...' }
];

var html = Styledown.parse(files);

html will only include markup from config.md (as a template) and app.less for the styleguide. If you swap config.md and link.less, html will include output from all files, as expected.

Styledown failes to proccess css example into html

Hello,

I am trying to compile one of your examples here: https://github.com/styledown/styledown/tree/master/examples/bootstrap

After typing make in my terminal my index.html loooks like this:

{ "files": { "buttons.css": { "name": "buttons.css", "title": null, "sections": {} }, "forms.css": { "name": "forms.css", "title": null, "sections": {} }, "lists.css": { "name": "lists.css", "title": null, "sections": {} }, "panels.css": { "name": "panels.css", "title": null, "sections": {} }, "tabs.css": { "name": "tabs.css", "title": null, "sections": {} }, "progress.css": { "name": "progress.css", "title": null, "sections": {} }, "components.css": { "name": "components.css", "title": null, "sections": {} }, "_extras.css": { "name": "_extras.css", "title": "Styleguide options", "sections": { "styleguide-options": { "id": "styleguide-options", "title": "Styleguide options", "depth": 1, "parts": { "s1": { "type": "text", "id": "s1", "content": "</li>\n<li></li>\n<li>" } } }, "head": { "id": "head", "title": "Head", "depth": 3, "parts": { "s1": { "type": "text", "id": "s1", "content": "</li>\n<li></li>\n<li>\n<pre><code>meta(name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;)\n</code></pre>\n</li>\n<li>\n<pre><code>link(rel='stylesheet' href='https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css')\n</code></pre>\n</li>\n<li>\n<pre><code>link(rel='stylesheet' href='_extras.css')\n</code></pre>\n</li>\n<li>\n<pre><code>link(rel='stylesheet' href='../../data/styledown.css')\n</code></pre>\n</li>\n<li>\n<pre><code>script(src='../../data/styledown.js')\n</code></pre>\n</li>\n<li></li>\n<li>" } } }, "body": { "id": "body", "title": "Body", "depth": 3, "parts": { "s1": { "type": "text", "id": "s1", "content": "</li>\n<li></li>\n<li>\n<pre><code>.jumbotron.jumbotron-styleguide\n</code></pre>\n</li>\n<li>\n<pre><code> .container\n</code></pre>\n</li>\n<li>\n<pre><code> h1 Bootstrap styleguides\n</code></pre>\n</li>\n<li>\n<pre><code> p\n</code></pre>\n</li>\n<li>\n<pre><code> | This is a sample styleguide for Bootstrap that was generated using\n</code></pre>\n</li>\n<li>\n<pre><code> | Styledown, a styleguide generator. They were taken from inline comments\n</code></pre>\n</li>\n<li>\n<pre><code> | in the CSS.\n</code></pre>\n</li>\n<li>\n<pre><code> p\n</code></pre>\n</li>\n<li>\n<pre><code> a.btn.btn-default(href=&quot;https://github.com/styledown/styledown&quot;) About Styledown\n</code></pre>\n</li>\n<li>\n<pre><code> a.btn.btn-default(href=&quot;https://github.com/styledown/styledown/tree/master/examples/bootstrap&quot;) See sources\n</code></pre>\n</li>\n<li>\n<pre><code>.container\n</code></pre>\n</li>\n<li>\n<pre><code> div(sg-content)\n</code></pre>\n</li>\n</ul>\n<p>*/</p>\n<p>@import url(http://fonts.googleapis.com/css?family=Source+Sans+Pro:700,400,300);</p>\n<p>/*</p>\n<ul>\n<li>jumbotron for the styleguide.\n*/</li>\n</ul>\n<p>.jumbotron-styleguide {\nbackground: #fafafa;\nborder-bottom: solid 1px #eee;\ntext-align: center;\nfont-family: 'Source Sans Pro', sans-serif;</p>\n<p>text-rendering: optimizeLegibility !important;\n-webkit-font-smoothing: antialiased !important;\n-moz-osx-font-smoothing: grayscale;\n}</p>\n<p>.jumbotron-styleguide h1 {\nfont-family: 'Source Sans Pro', sans-serif;\nfont-weight: 100;\ncolor: #111;\nfont-size: 3.4em;\nmargin-bottom: 20px;\n}</p>\n<p>.jumbotron-styleguide p {\nfont-weight: 400;\nfont-size: 1.15em;\nline-height: 1.7;\ncolor: #222;\n}</p>\n<p>.jumbotron-styleguide .btn {\nfont-family: 'Source Sans Pro', sans-serif;\ntext-transform: uppercase;\nfont-weight: bold;\nfont-size: 0.8em;\nletter-spacing: 1px;\npadding: 10px 30px;\nmargin: 10px 5px 0 5px;\ncolor: #1a8;\nborder-color: #ddd;\n}</p>\n<p>.jumbotron-styleguide .btn:hover {\nbackground: #1a8;\nborder-color: transparent;\ncolor: #fff;\n}</p>\n<p>.jumbotron-styleguide .container {\nmax-width: 500px;\n}</p>\n<p>/*</p>\n<ul>\n<li>override heading styles.\n*/</li>\n</ul>\n<p>h2.sg.sg {\nfont-family: 'Source Sans Pro', sans-serif;\nfont-weight: 300;\nfont-size: 3em;\n}</p>\n<p>/*</p>\n<ul>\n<li>for @example.slim\n*/</li>\n</ul>\n<p>.sg-slim .sg-canvas {\nmax-width: 300px;\n}</p>\n<p>/*</p>\n<ul>\n<li>for @example.wide\n*/</li>\n</ul>\n<p>.sg-wide .sg-canvas {\nmax-width: 540px;\n}</p>" } } } } } } }

I am using Node 6.3.0 on OSX 10.11

Can you assist ?

Michał

Jade indentation rules

Hi, I have a question regarding the indentation rules for examples within the documentation blocks, especially when using Jade notation.

The only way which was working for me was the following one, which you are using in examples.

Basically, that you need to indent four spaces from the left (orange) line, which gets you to the 9th character on the line (odd number) and it kind of breaks the editor indentation using tab key. Is any workaround possible for this? And is it also possible to indent two characters less for the whole example block (i.e. only two from the left line)?

Thanks for the information.

Image source in inline css comment

Hi! I was wondering if it is possible to add a image (source attribute with a image url) in a example (inline comment) ?

like:

div.thisisadiv
img (somehow with a source and a url?)

Couldn't run it on Windows

Even when I added it to my PATH in my system env. variables (actually tested in win10) manually, it wouldn't work. I have the npm path added, also.

Only way of making it work for me was calling it with node, like:

'node "C:/Users/**my_user**/AppData/Roaming/npm/node_modules/styledown/bin/styledown" ./css/style.css ./scss/config.md > ./docs/index.html' 

Note: I had no issues on Linux. Worked just fine out-of-the-box.

Concatenate sections

Would it be possible to concatenate sections which have the same titles of the following format?:

/***
 * Buttons
 */

I have button styles in different files and I would like to add them all to the same section instead of having multiple sections with the same title in different locations within the style guide.

html attributes in styledown comments

Hi! I can't find out if it's possible to add custom attributes in the markdown comments or not. Do markdown even support this out of the box?

What I want to do is to add a type="password" attribute to a input element.

At the moment, my comment looks like this:

/**
 * Forms:
 * Description here.
 *
 *     @example
 *     form
 *       div.form-item
 *         label Required textfield
 *           span.form-required *
 *         input
 *       div.form-item
 *         label Required password
 *           span.form-required *
 *         input
 */

I would like to add the attribute type="password" to the password field. Is this even possible?

Ignore comment block

Is it somehow possible to ignore a comment block, currently?

Cofigure title tag

is it possible to configure the title of the stylesheet?
something like
title("My Styleguide Title")

eh?

Option to use Sass Comment Style

I need to Styledown read scss files, but i don't want to theses comments went to the final css file. All comments in my scss files are stripped with dual slashes (//).

Can i use Styledown with this type of comment?

Config not read

Hi, cool library! Having a problem with configuring it though. I wrote the default config to config.md, then I call

styledown -i web/wp-content/themes/britco-responsive/_compiled/css/main.css ./config.md

Instead of having a head and body section, the HTML starts with
<p class="sg">

Styledown: Command Not Found

I noticed that this tool hasn't been updated in some time so I'm wondering if its now abandoned, but while trying to test out styledown I get a command not found error in the terminal.

It might be safe to assume this is failing because of newer versions of node. Even running styledown --help returns command not found.

Node version: 6.4.0
npm version: 3.10.3
Running on Mac OSX 10.11.6

Any thoughts?

Api problem when passing list of files

I'm trying to use styledown within a nodejs script and I can't manage to make it works :(
I've read the API.md file, and quickly tried this :

var Styledown = require('styledown');
var docs = [
    { name: 'buttons.less', data: '' }
];
console.log(Styledown.parse(docs));

The documentation doesn't explain what is the data parameter, so I let it blank

It doesn't work, output is empty string.
then I tried :

...
    { name: 'buttons.less', data: '### hello *world*' }
...

And it returns an empty string again

Then I did :

...
    { name: 'buttons.XXX', data: '### hello *world*' }
...

and then my output was html created with the MD string set in the data field.

After reading that part of the code :

  extract: function (src) {
    var self = this;

    if (typeof src === 'string')
      return src;

    if (Array.isArray(src)) {
      return src.map(function (f) {
        if (self.options.inline || f.name && f.name.match(/(sass|scss|styl|less|css)$/)) {
          return mdextract(f.data, { lang: 'css' }).toMarkdown();
        } else {
            return f.data;
        }
      }).join("\n");
    }
  },

extract seems to be a function returning a MD string.
when src is a string it returns the string as it. That's ok.
when srcis an array BUT names provided are not (sass|scss|styl|less|css) or inline options is not used, it returns the concatenation of all MD strings passed in with the "data" parameters. That's OK too.
when srcis an array with filenames, it uses mdextract to get the MD inside the file but f.data is passed as first parameters instead of the content of the file (the file is never read, anywhere)

mdextract seems to not be able to read file, so I suppose we should read the file and pass the content to mdextract

Am I wrong somewhere ?

-bash: styledown: command not found

Hi, after the installation the styledown command can't be found:

npm install -g styledown
styledown --help
-bash: styledown: command not found

The same result for Ubuntu 5.4.0-6ubuntu1~16.04.4 and MacOs High Sierra.

ENOENT: no such file or directory

I'm trying to employ Styledown for the first time and have had good results using v1.02 and specifying markdown files plus a markdown config file:

styledown components/a/example.md components/b/example.md styledownConf.md > docs/styleguide.html

When I tried to go for the wildcard: styledown components/*.md styledownConf.md > docs/styleguide.html I received the following error:

ENOENT: no such file or directory

The documentation shows the use of a wildcard character for both scss and md, so I'm curious if anyone has insights on this.

Adding a Basic Markdown page.

I'm trying to build out a documentation page on an internal project. I'm assuming I can just create a page that is called about.md and write it out as markdown then compile it separately.

It all works great and the config template is added. but then it looks like it is adding template code again below the contents wrapped in a tag.

Update: If I remove the list items either ordered or unordered this issue goes away.

Use `node-glob` to properly cross-platform expand globbing syntax

the library you're using to expand input files doesn't do anything smart with globbing syntax.

so the following use cases with either not match files or miss out deeply nested directories:

• styledown config.md src/styles/**/*{-*,}.scss > ./dist/styleguide.html
• styledown config.md **/*.scss > ./dist/styleguide.html

Suggest you wrap your argv._ with node-glob to more effectively expand globbing.

Documentation page title

Hi, it would be nice to allow a change of the <title> tag of the exported styleguide. Now, you use <title>Styledown</title> which is ok, but could this be editable via config?

Difference from KSS, Styledocco and why to create yet another CSS doc parser

Hi,

I am the founder and maintainer of SourceJS Living Style guide engine, based on JavaScript (NodeJS and client).

I'm investigating the current state of Living Style Guide tools for one of my public talks and few articles on the topic. Could you please answer few questions:

1. What is the core difference of this project from KSS-node, Styledocco and other similiar CSS focused tools?
2. Why you don't consider sharing efforts with other authors of nodejs based tools, creating a common, modular documentation generator?
3. I have some plans for integration some of CSS documentation parsing tools with SourceJS engine, do you plan to have additional feature, that will just generate raw data in JSON as an output? This will help transforming this kind of raw data to all kind of HTML outputs.

Not using Sass nor concatenating files

I know I probably should be using Sass and have a more modular approach to my styles, but is there a way to use StyleDown if all your components are in one CSS file?