Skip to content

Commit b3bb32b

Browse files
robhrt7robhrt7
committed
#123: add spec rendering helpers doc
1 parent ad17ec3 commit b3bb32b

File tree

9 files changed

+131
-3
lines changed

9 files changed

+131
-3
lines changed

‎docs/base/readme.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,8 @@ By default all files are pre-processed with [EJS](http://ejs.co/), so you're fre
118118
<% if (info.title === 'Title') {% > Action! <% } %>
119119
```
120120

121+
<a href="/docs/spec-helpers" class="source_a_hl">Read more about Spec page generation helpers.</a>
122+
121123
### Client-side Templating Engines
122124

123125
For client-side templating you don't need any magic, just link Mustache or any other JS library to your page and use it whenever you want.
@@ -167,11 +169,12 @@ As a Style Guide Platform we focus on flexibility and ease of integration. All S
167169

168170
Plugins are working in the same way as core modules, but are kept outside the main platform, allowing to separate specific features.
169171

170-
Here is a list of official plugins:
172+
Here is a list of available plugins:
171173

172-
* [sourcejs-md-react](https://www.npmjs.com/package/sourcejs-md-react) (new)
174+
* [sourcejs-slm](https://github.com/venticco/sourcejs-slm) (new)
175+
* [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) (new)
173176
* [sourcejs-contrib-browser-sync](https://github.com/sourcejs/sourcejs-contrib-browser-sync) (new)
174-
* [sourcejs-react](https://www.npmjs.com/package/sourcejs-react) (new)
177+
* [sourcejs-react](https://github.com/szarouski/sourcejs-react) (new)
175178
* [sourcejs-contrib-dss](http://github.com/sourcejs/sourcejs-contrib-dss) (new)
176179
* [sourcejs-spec-status](https://github.com/sourcejs/sourcejs-spec-status)
177180
* [sourcejs-crowd-voice](https://github.com/sourcejs/sourcejs-crowd-voice)

‎docs/spec-helpers/examples/buttons.html

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<h2><%- info.title %></h2>
2+
3+
<% var buttons = ['btn-group-lg', '', 'btn-group-sm', 'btn-group-xs'] %>
4+
5+
<% buttons.forEach(function(modifier){ %>
6+
<div class="btn-group <%= modifier %>" role="group" aria-label="Default button group">
7+
<button type="button" class="btn btn-default">Left</button>
8+
<button type="button" class="btn btn-default">Middle</button>
9+
<button type="button" class="btn btn-default">Right</button>
10+
</div><br><br>
11+
<% }); %>

‎docs/spec-helpers/examples/include.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Included file from `spec-helpers/examples/include.html`.

‎docs/spec-helpers/examples/markdown-file.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Processed **Markdown** file.

‎docs/spec-helpers/examples/mask-one.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
one<br>

‎docs/spec-helpers/examples/mask-two.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
two<br>
2+
<%- includeFiles('three.html') %>

‎docs/spec-helpers/examples/three.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
three<br>

‎docs/spec-helpers/info.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"keywords": "ejs, include",
3+
"title": "Spec Rendering Helpers",
4+
"template": "doc"
5+
}

‎docs/spec-helpers/readme.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
## Intro
2+
3+
Spec pages in SourceJS engine are the main content units. They provide a proper sandbox for demoing rendered components, usage examples and module documentation. Therefore, it's really important to make Spec pages development process as easy as possible.
4+
5+
Apart from plugins, that allow integrating different technologies for generating Specs pages, the engine provides a set of native helpers based on [EJS](http://ejs.co).
6+
7+
Let's dive deeper into each of available Spec generation features.
8+
9+
## Plugins
10+
11+
It's really important for us to make SourceJS easy adaptable to any project needs. Having a powerful, and easy-to-develop plugins system hugely improves developers user experience working with Living Style Guides.
12+
13+
Here's a list of all Spec generation focused plugins:
14+
15+
* [sourcejs-slm](https://github.com/venticco/sourcejs-slm) - [Slim](http://slim-lang.com/) templates support
16+
* [sourcejs-md-react](https://github.com/mik01aj/sourcejs-md-react) - Markdown helpers for rendering React components
17+
* [sourcejs-react](https://github.com/szarouski/sourcejs-react) - generate specs from JSX files
18+
* [sourcejs-contrib-dss](http://github.com/sourcejs/sourcejs-contrib-dss) - generating documentation out of CSS comments
19+
* [sourcejs-jade](https://github.com/sourcejs/sourcejs-jade) - [Jade](http://jade-lang.com/) syntax support
20+
21+
Most of the plugins have [live examples](http://sourcejs.com/specs/example-specs-showcase/) on the project website.
22+
23+
## Native Templating
24+
25+
SourceJS uses powerful [EJS](http://ejs.co/) templating engine for core UI generation and Specs content processing. This means that any Spec file can use the full power of EJS templating logic.
26+
27+
```html
28+
&lt;% if (info.title === 'Title') {% &gt; Action! &lt;% } %&gt;
29+
```
30+
31+
Use plain JavaScript for managing conditions and generating demo content through data loops. All `info.json` file contents are by default available in each Spec scope. Apart from common [meta information](/docs/info-json) available in `info.json` files, it's possible to set any of your own custom data.
32+
33+
```html
34+
&lt;h2&gt;&lt;%- info.title %&gt;&lt;/h2&gt;
35+
36+
&lt;% var buttons = ['btn-group-lg', '', 'btn-group-sm', 'btn-group-xs'] %&gt;
37+
38+
&lt;% buttons.forEach(function(modifier){ %&gt;
39+
&lt;div class="btn-group &lt;%= modifier %&gt;" role="group" aria-label="Default button group"&gt;
40+
&lt;button type="button" class="btn btn-default"&gt;Left&lt;/button&gt;
41+
&lt;button type="button" class="btn btn-default"&gt;Middle&lt;/button&gt;
42+
&lt;button type="button" class="btn btn-default"&gt;Right&lt;/button&gt;
43+
&lt;/div&gt;&lt;br&gt;&lt;br&gt;
44+
&lt;% }); %&gt;
45+
```
46+
47+
```example
48+
<%- include('examples/buttons.html') %>
49+
```
50+
51+
### Includes
52+
53+
Providing a relative path to current Specs, it's easy to include any file.
54+
55+
```html
56+
&lt;%- include('examples/include.html') %&gt;
57+
```
58+
59+
```example
60+
<%- include('examples/include.html') %>
61+
```
62+
63+
Note that by default, SourceJS restricts including files outside project directory for security reasons. To disable this restrictions, change `core.sandboxIncludes` configuration.
64+
65+
<a href="https://github.com/sourcejs/Source/tree/master/docs/spec-helpers/examples" class="source_a_hl">View examples source code.</a>
66+
67+
68+
## EJS Custom Helpers
69+
70+
Starting from v.0.5.6, SourceJS provides a set of custom EJS helpers:
71+
72+
* `includeMD(path)` - include and process Markdown file
73+
* `includeFiles(glob)` - include a set of files by mask (uses [glob](https://github.com/isaacs/node-glob))
74+
75+
Feel free to create Pull Requests with a wider set of helpers.
76+
77+
### includeMD
78+
79+
```html
80+
&lt;%- includeMD('examples/markdown-file') %&gt;
81+
```
82+
83+
```example
84+
<%- includeMD('examples/markdown-file') %>
85+
```
86+
87+
### includeFiles
88+
89+
```html
90+
&lt;%- includeFiles('examples/mask-*.html') %&gt;
91+
```
92+
93+
```example
94+
<%- includeFiles('examples/mask-*.html') %>
95+
```
96+
97+
<a href="https://github.com/sourcejs/Source/tree/master/docs/spec-helpers/examples" class="source_a_hl">View examples source code.</a>
98+
99+
## Extended features
100+
101+
For any other custom Spec content processing, we recommend building own SourceJS plugins. Follow our [instructions](/docs/api/plugins/) and example plugins for fast kick-off.
102+
103+
It's also possible to configure custom build task, that will generate compatible Spec pages via Grunt/Gulp or any other build tool.

0 commit comments

Comments
 (0)