styledown/Readme.md

Styledown
=========

A markdown dialect to help you write CSS styleguides efficiently.

[![Status](https://travis-ci.org/rstacruz/styledown.png?branch=master)](https://travis-ci.org/rstacruz/styledown)

Warning
-------

**Work-in-progress** (but usable), not feature-complete (but near), and not 
fully documented (but will be). Use if you're adventurous (via git clone + npm 
link).

What to do
----------

Write your CSS documentation with an `h3`, and a code block that begins with 
`@example`.

``` markdown
### Button

Create your buttons with a `.button` class.

    @example
    <a class="button">Button</a>
    <a class="button primary">Button</a>
```

Jade is also supported. It's auto-detected for you when you want Jade or HTML.

``` markdown
### Tables

Tables have a class `.table`.

    @example
    table.table
      tr
        td Item 1
        td Item 2
        td Item 3
```

Differences from regular markdown
---------------------------------

Styledown works like Markdown: it merely transforms a document into HTML. In 
fact, any and all Markdown documents will work as expected in Styledown.

With a few key extensions:

### Example blocks

Example blocks are regular code blocks that begin with `@example`. They're 
rendered into HTML + source code blocks.

#### Input

``` markdown
Consider this example:

    @example
    <a class="button">Button</a>
    <a class="button primary">Button</a>
```

#### Output

``` html
<p>Consider this example:</p>

<div class="sg-example">
  <!-- Actual HTML code is rendered here in `.sg-canvas` -->
  <div class="sg-canvas">
    <a class="button">Button</a>
    <a class="button primary">Button</a>
  </div>

  <!-- Syntax-highlighted source code here in `.sg-code` -->
  <pre class="sg-code">
    &lt;a class="button"&gt;...
  </pre>
</div>
```

### Syntax highlighting

Syntax highlighting comes for free, without any client-side code. Simply 
surround your code in a code fence, and it will be highlighted via 
[highlight.js].

#### Input

    See this code:

    ``` javascript
    $(function() {
      alert("Hello");
    });
    ```

#### Output

``` html
<p>See this code:</p>

<pre class="sg-lang-javascript">
$(<span class='hljs-function'>function</span>() {
   alert(<span class='hljs-string'>"hello"</span>);
});
</pre>
```

### Also

 * Sections
 * blocks
 * Syntax highlighting
 * Example blocks

Installation
------------

``` bash
$ npm install -g styledown
```

Usage
-----

### Command line

``` bash
$ styledown < Styles.md > index.html
```

### Node.js

``` js
var Styledown = require('styledown');
Styledown.parse(string);
```

### Node.js - Express

Use the middleware.

``` js
var styledownHandler = require('styledown/connect');
app.use(styledownHandler({
  path: '/styleguides',
  root: Dir.cwd(),
  guides: {
    index: 'styles.md',
    forms: 'forms.md'
  }
});
```

### Ruby

To come soon.

### Ruby - Rails

Middleware to come soon.

Getting started
---------------

Write your files in Markdown.

License
-------

Released under the MIT License. Copyright (c) 2014 Rico Sta. Cruz.

> Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
>
> The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.