You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/auth/readme.md
+9-2
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,9 @@ After that, auth feature is able to use.
21
21
22
22
### Client-side auth control
23
23
24
-
Github auth module includes client-side controll. It should be included into your `header.inc.html` (if you have the overridden one). Here is the example:
24
+
GitHub login module should be embedded into your `header.inc.html` or any other place you want.
25
+
26
+
Here is the example:
25
27
26
28
```html
27
29
<!-- header.inc.html content-->
@@ -33,13 +35,15 @@ Auth uses `js-hook` and `source_login` classes for targeting. This hook is defin
33
35
34
36
## Auth configuration
35
37
36
-
Auth configuration is availible from your instance options, as it was mentioned above. Here is the full options list:
38
+
Auth configuration is available from your instance [options](/docs/base/#configuration), as it was mentioned above. Here's few of available options:
Copy file name to clipboardExpand all lines: docs/base/readme.md
+18-24
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ $ cd sourcejs-folder
19
19
$ yo sourcejs
20
20
```
21
21
22
-
If you're running Windows, and have some issues with [jsdom](https://github.com/tmpvar/jsdom) dependencies compilation, check this [topic](https://github.com/sourcejs/Source/issues/23).
22
+
If you're running Windows and have some issues with [jsdom](https://github.com/tmpvar/jsdom) dependencies compilation, check this [topic](https://github.com/sourcejs/Source/issues/23).
23
23
24
24
### Run Commands
25
25
@@ -31,9 +31,9 @@ $ node app
31
31
32
32
For first dev build Grunt will run automatically right after Yeoman init, here's a list of [all Grunt tasks available](/docs/grunt).
33
33
34
-
## First spec
34
+
## Creating First Spec
35
35
36
-
Specs are the main content files in SourceJS engine, in them you define all your description of chosen components and it's code examples. Originally we use `*.src` file templates, but you're free to configure your own with [Jade](https://github.com/sourcejs/sourcejs-jade) for example.
36
+
Specs are the main content files in SourceJS engine, in them you define all your description of chosen components and it's code examples. Originally we use `*.src`and `*.md`file templates, but you're free to configure your own technologies with plugins, like[Jade](https://github.com/sourcejs/sourcejs-jade) for example.
37
37
38
38
<divclass="source_note">
39
39
After initialization, you get `sourcejs/user` folder, which is the place for all your custom content. All new Specs and configuration of main engine must be done there.
@@ -47,32 +47,24 @@ The starting template for new **Spec** pages can be found in [/docs/starting](/d
47
47
48
48
### Server-side Templating Engines
49
49
50
-
As we mentioned before, it's easy to use other server-side/compiled templating engines like Jade, you only need to create a simple SourceJS middleware ([example](https://github.com/sourcejs/sourcejs-jade)) or process your sources with Grunt/Gulp. `*.src` files, that we use by default are processed with [EJS](https://github.com/tj/ejs), so you're free to use custom EJS features in any spec page - like includes or even plain JavaScript.
50
+
As we mentioned before, it's easy to use other server-side/compiled templating engines like Jade, you only need to create a simple SourceJS middleware ([example](https://github.com/sourcejs/sourcejs-jade)) or process your sources with Grunt/Gulp.
51
+
52
+
`*.src` files, that we use by default are processed with [EJS](https://github.com/tj/ejs), so you're free to use custom EJS features in any spec page - like includes or even plain JavaScript.
51
53
52
54
We treat Spec files as an interface, you can construct your Spec page in any ways, following only few simple rules - each Spec must have `info.json` file aside, with meta information for the Engine and output spec page must have SourceJS compliant markup. Special markup contains only few vital classes like `.source_section`, `.source_example` and the rest is plain, semantic HTML.
53
55
54
56
### Client-side Templating Eninges
55
57
56
-
For client-side templating you don't need any magic, just link Mustache or any other technology to your page and use it whenever you want. Remember, SourceJS Specs are a simple static pages, that are then enchanted with client-side scripts and internal APIs.
57
-
58
-
After 0.4 release we will put quite a lot of effort, creating example with popular technologies for fast scaffolding your SourceJS library.
58
+
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. Remember, SourceJS Specs are a simple static pages, that are then enchanted with client-side scripts and internal APIs.
59
59
60
60
## Examples
61
61
62
-
Main project website [Sourcejs.com](http://sourcejs.com) is based on SourceJS engine, as well as all documentation that you're surfing right now. To see more complex example of Spec page, check out [this section](/docs/spec/).
62
+
Main project website [Sourcejs.com](http://sourcejs.com) is based on SourceJS engine, as well as all documentation that you're surfing right now. To see more complex example of Spec page, check out [this spec](/docs/spec/).
63
63
64
64
You can inspect [Sourcejs.com source code](https://github.com/sourcejs/Sourcejs.com), that demonstrates basic `source/user` folder contents.
65
65
66
66
More examples and screencasts coming soon, but for now, you can check this [SourceJS video presentation](https://www.youtube.com/watch?v=ukFeZnJjrLs) (RU with EN subtitles).
67
67
68
-
## File Structure
69
-
70
-
Engine architecture is based on **two enviroments:**
71
-
72
-
73
-
***assets** - JavaScript front-end
74
-
***core** - NodeJS back-end
75
-
76
68
## Configuration
77
69
78
70
All default options for `assets` (front-end) and `core` (back-end) are located in `sourcejs/options.js`. To overwrite basic options, user your own `sourcejs/user/options.js` file, from your SourceJS instance home directory.
@@ -120,14 +112,16 @@ Plugins could have `core` and `assets` parts to improve both back-end and front-
Required attribute `data-nav`names the catalogue to be displayed. Inserting mentioned code in any Source page a navigation like this will be generated:
13
+
`data-nav`attribute defines the catalogue to be displayed. Inserting mentioned code in any Source page a navigation like this will be generated:
14
14
15
15
<divclass="source_catalog"data-nav="/docs"></div>
16
16
17
17
18
-
### Absolute pathя
18
+
### Absolute path
19
19
20
20
We recommend using absolute paths, as they are more stable and predictable.
Copy file name to clipboardExpand all lines: docs/spec/index.src
+17-10
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,9 @@
1
1
<h1>Spec Page Documentation</h1>
2
2
3
3
<div class="source_info">
4
+
<p>This page highlights the basic features of SourceJS documentation pages that we call Specs. To create your own Spec, follow this <a href="/docs/base/#creating-first-spec">short guide</a>.</p>
4
5
5
-
<p>You can add info blocks to spec pages by adding <code>.source_info</code> to a div:</p>
6
-
7
-
<p>Specs are generated directly from the <span class="source_hl">/user</span> folder in Source's <a href="/docs/base#2">file structure</a>. To create a new spec page like this one, make a copy of the <a href="/docs/starting">starting template</a> folder in <span class="source_hl">/user/docs</span>.</p>
8
-
6
+
<p>For text description, SourceJS uses basic HTML markup, and custom CSS class hooks. To render highlighted description block like this, add <code>.source_info</code> class to a any HTML element on page.</p>
9
7
</div>
10
8
11
9
<div class="source_warn">
@@ -77,7 +75,7 @@
77
75
</div>
78
76
</div>
79
77
80
-
<p>To render and highlight the source code, wrap it in <code><code class="src-html"></code>, <code><code class="src-css"></code> or <code><code class="src-js"></code> tags, depending on the language you want to highlight, like this:</p>
78
+
<p>To render and highlight the source code, wrap it in <code><code class="src-html"></code>, <code><code class="src-css"></code><br> or <code><code class="src-js"></code> tags, depending on the language you want to highlight, like this:</p>
81
79
<code class="src-html source_visible">
82
80
<code class="src-html">
83
81
<div class="foo">Bar</div>
@@ -107,7 +105,7 @@
107
105
<section class="source_section">
108
106
<h2>Linking Your Project's CSS</h2>
109
107
110
-
<p>Your project's CSS should be linked to each spec page to render your examples, and you can also add styles specific to a spec page:</p>
108
+
<p>Your project's CSS should be linked to each spec page to render your examples using <code>/user/core/views/spec.ejs</code>, or you can also add styles specific to a spec page:</p>
111
109
112
110
<code class="src-html source_visible">
113
111
<!-- Your project styles -->
@@ -124,9 +122,7 @@
124
122
<section class="source_section">
125
123
<h2>Spec Page Markup</h2>
126
124
127
-
<h3>Documentation Text</h3>
128
-
129
-
<p>Only the following tags in documentation sections are styled by Source:</p>
125
+
<p>SourceJS Specs support styling of these semantic HTML tags, that you could use to describe your sections:</p>
130
126
131
127
<ul>
132
128
<li><code>p</code></li>
@@ -142,7 +138,18 @@
142
138
143
139
<p>This styling <strong>is not applied inside example blocks</strong>.</p>
144
140
145
-
<p>Markdown support for editing documentation sections will be available within the next few updates.</p>
141
+
<p>From 0.5.0 SourceJS fully supports Markdown based Specs as well. You can use <code><markdown></code> tag in any Spec templates including <code>index.src</code>, or just use <code>readme.md</code> templates instead.</p>
142
+
143
+
<p><a href="/docs/markdown">Read more about markdown support</a></p>
144
+
145
+
</section>
146
+
147
+
<section class="source_section">
148
+
<h2>Source code</h2>
149
+
150
+
<p>
151
+
This spec uses <code>index.src</code> template, view it's <a href="index.src">source</a>.
0 commit comments