README-SPEC.md

Stylemark Spec

Stylemark is an extension of GitHub-flavored Markdown with executable code blocks.

Executable code blocks

A fenced code block with a name will be identified as an executable example. To name a code block, prefix the language string with the name followed by a period, eg. name.js. Names can have any characters except whitespace or periods.

Example

This HTML code block defines an example named button-types and will be rendered as a real HTML example.

```button-types.html
<button class="btn btn-default">Default</button>
<button class="btn btn-primary">Primary</button>
<button class="btn btn-success">Success</button>
```

Executable examples can have more than just HTML. You can include JS, CSS, JSX, Angular, etc. through additional code blocks that share the same name.

Example

These code blocks define a hello example with HTML, JS, and CSS. All JS and CSS will be sandboxed to the HTML.

```hello.html
<button>Say Hello</button>
```
```hello.js
$('button').click(function() { alert('Hello!'); });
```
```hello.css
button {
    background: green;
}
```

Sometimes it's desirable to execute a code block but hide its source code. Code blocks can be marked as hidden by including a hidden option in the fenced code block definition.

Example

The CSS styling will be applied to the button, but the CSS source will not be shown.

```padded.html
<button>Click me</button>
```
```padded.css hidden
button {
	display: block;
	margin: 20px;
}
```

External example files

Additionally, you can reference code written in external files, using the following syntax:

```<name>:<path>
```

where:

<name> is the example name (without file extension)

<path> is the filepath, by default relative to the current file. If prefixed with /, then the path will be relative to the root project directory (ie. the first ancestor directory that contains package.json).

Example

This first example uses a 'data' object from a shared JS file:

```example-1.js
console.log('Example 1: ' + data);
```
```example-1:/path/to/data/data.js
```

This second example uses the same shared JS file:

```example-2.js
console.log('Example 2: ' + data);
```
```example-2:/path/to/data/data.js
```

Where /path/to/data/data.js contains:

data = { … }

Wildcards

Given the following files:

// in /path/to/data/data.js:
data = { … }

// in /path/to/somewhere/foo.html:
Data: <div id="data"></div>

// in /path/to/somewhere/bar.js:
document.getElementById('data').innerHTML = JSON.stringify(data);

you could write:

```example-3:/path/to/data/data.js
```
```example-3:/path/to/somewhere/*
```

which would be equivalent to this inline version:

```example-3.js
data = { … }
```
```example-3.html
Data: <div id="data"></div>
```
```example-3.js
document.getElementById('data').innerHTML = JSON.stringify(data);
```