Markdown-based styleguide generator

Styledown

Last update: Nov 21, 2022

Related tags

CSS styledown

Overview

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;
  ...
}

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.

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

©️

ricostacruz.com · GitHub @rstacruz · Twitter @rstacruz

Comments

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?

opened by erwstout 7
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 
opened by pdufour 4
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="viewport" content="width=device-width, initial-scale=1")\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="https://github.com/styledown/styledown") About Styledown\n</code></pre>\n</li>\n<li>\n<pre><code> a.btn.btn-default(href="https://github.com/styledown/styledown/tree/master/examples/bootstrap") 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*/\n@import url(http://fonts.googleapis.com/css?family=Source+Sans+Pro:700,400,300);\n/*\n<ul>\n<li>jumbotron for the styleguide.\n*/</li>\n</ul>\n.jumbotron-styleguide {\nbackground: #fafafa;\nborder-bottom: solid 1px #eee;\ntext-align: center;\nfont-family: 'Source Sans Pro', sans-serif;\ntext-rendering: optimizeLegibility !important;\n-webkit-font-smoothing: antialiased !important;\n-moz-osx-font-smoothing: grayscale;\n}\n.jumbotron-styleguide h1 {\nfont-family: 'Source Sans Pro', sans-serif;\nfont-weight: 100;\ncolor: #111;\nfont-size: 3.4em;\nmargin-bottom: 20px;\n}\n.jumbotron-styleguide p {\nfont-weight: 400;\nfont-size: 1.15em;\nline-height: 1.7;\ncolor: #222;\n}\n.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}\n.jumbotron-styleguide .btn:hover {\nbackground: #1a8;\nborder-color: transparent;\ncolor: #fff;\n}\n.jumbotron-styleguide .container {\nmax-width: 500px;\n}\n/*\n<ul>\n<li>override heading styles.\n*/</li>\n</ul>\nh2.sg.sg {\nfont-family: 'Source Sans Pro', sans-serif;\nfont-weight: 300;\nfont-size: 3em;\n}\n/*\n<ul>\n<li>for @example.slim\n*/</li>\n</ul>\n.sg-slim .sg-canvas {\nmax-width: 300px;\n}\n/*\n<ul>\n<li>for @example.wide\n*/</li>\n</ul>\n.sg-wide .sg-canvas {\nmax-width: 540px;\n}" } } } } } } }

I am using Node 6.3.0 on OSX 10.11

Can you assist ?

Michał

opened by padsbanger 2
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.
opened by gangsthub 2
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.
opened by SammyM 2
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?)

opened by myurtsev 1
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.
opened by jermartin77 1












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?



opened by josephrexme  1














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?



opened by skube  1














-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.



opened by Gugols  1














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.



opened by markedwardsims  1














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.



opened by airtonix  0














Add --case-sensitive option




What does this PR do?
Adds a new --case-sensitive option that forces the HTML generated by Styledown to retain attribute and element casing. This is useful for SVG and Angular2 markup where case sensitivity is important.



opened by soulfresh  0