-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
333 lines (270 loc) · 22.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cadmium.js</title>
<!-- favicon -->
<link rel="icon" type="image/gif" href="assets/img/favicon.gif?nocache=00ee" />
<!-- cdn -->
<!-- css -->
<link href="assets/css/vendor/highlight/monokai.css" rel="stylesheet" type="text/css">
<link href="assets/css/vendor/font-awesome.min.css" rel="stylesheet" type="text/css">
<link href="assets/css/vendor/elastic.css" rel="stylesheet" type="text/css">
<link href="assets/css/reset.css" rel="stylesheet" type="text/css">
<link href="assets/css/button.css" rel="stylesheet" type="text/css">
<link href="assets/css/style.css" rel="stylesheet" type="text/css">
<!-- fonts -->
<link href="http://fonts.googleapis.com/css?family=Montserrat:400,700" rel="stylesheet" type="text/css">
<!-- js -->
<script src="assets/js/vendor/neon.js"></script>
<script src="assets/js/vendor/jquery.js"></script>
<script src="assets/js/vendor/ZeroClipboard.min.js"></script>
<script src="assets/js/vendor/elastic.js"></script>
<script src="assets/js/Cd.js"></script>
</head>
<body>
<!-- fork me ribbon -->
<a href="https://github.com/escusado/cadmium"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" alt="Fork me on GitHub"></a>
<!-- top color bar -->
<div class="top-line"></div>
<div class="wrapper">
<!-- header -->
<div class="header">
<a href="http://escusado.github.io/cadmium">
<img class="tm-icon" src="assets/img/icon.png" alt="Cadmium">
<div class="name">Cadmium<span>.js</span></div>
<div class="description">A simple Code documentation theme for your project</div>
</a>
</div>
<!-- content -->
<div class="content">
<!-- library presentation -->
<h1>What is it?</h1>
<p><a href="https://en.wikipedia.org/wiki/Cadmium" alt="Cadmium (Cd)" target="_blank">Cadmium (Cd)</a> is a node.js tool and a set of files that lets you create a site just like this so you can use it on <a target="_blank" href="http://pages.github.com/">Github Pages</a>.</p>
<a class="get-code" href="https://github.com/escusado/cadmium" target="_blank">
<div class="button get-code-button">
<i class="icon icon-github"></i>
<span> Get the code on Github! </span>
<div class="shade"></div>
</div>
</a>
<h2>Features</h2>
<ul>
<li><a href="#style-file">Configurable styles</a></li>
<li><a href="#proj">Json data api</a></li>
<li><a href="#code-blocks">Highlighted code blocks</a></li>
<li><a href="#render">Partials support</a></li>
<li><a href="#usage">Preview app with express.js</a></li>
</ul>
<!-- quick usage -->
<h2 id="usage">Usage</h2>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n//1. Get Cadmium files into your gh-pages branch\n> ls\n .gitignore\n assets\n views\n assets.json\n package.json\n project.json\n cadmium.js\n\n//2. Get the dependencies\n> npm install\n\n//3. Run Cadmium server\n> node cadmium.js\nCd ready on port: 3000\n\n//Visit http://localhost:3000\nParsing project.json\nParsing assets.json\nCreating context.\nRendering style and index file!\nindex.html File saved!\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="javascript">
<span class="comment">//1. Get Cadmium files into your gh-pages branch</span>
> ls
.gitignore
assets
views
assets.json
package.json
project.json
cadmium.js
<span class="comment">//2. Get the dependencies</span>
> npm install
<span class="comment">//3. Run Cadmium server</span>
> node cadmium.js
Cd ready on port: <span class="number">3000</span>
<span class="comment">//Visit http://localhost:3000</span>
Parsing project.json
Parsing assets.json
Creating context.
Rendering style and index file!
index.html File saved!
</code></pre></div>
<p>Cd will generate the <code>index.html</code> each time you reload your browser. This is the file that Github Pages displays.</p>
<!-- how it works -->
<h1>Tweak it!</h1>
<p>Cd its ment to be mess with. At this point the only thing you have to do is to customize the theme, content and data for your project, hack it at your convenience :)</p>
<h2>How it works?</h2>
<p>Cd has a very simple json and template system, it uses <a target="_blank" href="http://freshout-dev.github.io/thulium">Thulium</a> implementation of EJS to compile its views.</p>
<h3><i class="icon icon-folder-open"></i> /views</h3>
<p>The views are stored into the <code>views</code> folder, Cd by default will look for <code>views/index.ejs</code> to render it, so start there, you can <a href="#render">use partials</a> to organize your views.</p>
<h4>EJS</h4>
<p>Cd uses EJS for the templates, we are using the <a target="_blank" href="https://github.com/freshout-dev/thulium/blob/master/spec.md#tm-tags">Thulium flavor syntax</a>:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<!-- Execute code -->\n<% var myVariable = &dqu;This IS MY VariablE&dqu; %>\n\n<!-- print values -->\n<div><%= myVariable.toLowercase() %></div>\n\n<!-- Renders -->\n<div>this is my variable</div>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="comment"><!-- Execute code --></span>
<span class="vbscript"><% var myVariable = <span class="string">"This IS MY VariablE"</span> %></span>
<span class="comment"><!-- print values --></span>
<span class="tag"><<span class="title">div</span>></span><span class="vbscript"><%= myVariable.toLowercase() %></span><span class="tag"></<span class="title">div</span>></span>
<span class="comment"><!-- Renders --></span>
<span class="tag"><<span class="title">div</span>></span>this is my variable<span class="tag"></<span class="title">div</span>></span>
</code></pre></div>
<h3>Config files</h3>
<p>Cd uses 2 json files to work:</p>
<h4 id="project-file"><i class="icon icon-file"></i> /project.json</h4>
<p>This json file will hold your project data, Cd uses this values to render them in the views:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n{\n &dqu;name&dqu; : &dqu;Cadmium&dqu;,\n &dqu;lang&dqu; : &dqu;js&dqu;,\n &dqu;desc&dqu; : &dqu;A simple theme for your project&dqu;,\n &dqu;url&dqu; : &dqu;http://escusado.github.io/cadmium&dqu;,\n &dqu;githubUrl&dqu; : &dqu;https://github.com/escusado/cadmium&dqu;,\n &dqu;forkColor&dqu; : &dqu;orange&dqu;,\n &dqu;favicon&dqu; : &dqu;assets/img/favicon.gif&dqu;,\n &dqu;icon&dqu; : &dqu;assets/img/icon.png&dqu;\n}\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="javascript">
{
<span class="string">"name"</span> : <span class="string">"Cadmium"</span>,
<span class="string">"lang"</span> : <span class="string">"js"</span>,
<span class="string">"desc"</span> : <span class="string">"A simple theme for your project"</span>,
<span class="string">"url"</span> : <span class="string">"http://escusado.github.io/cadmium"</span>,
<span class="string">"githubUrl"</span> : <span class="string">"https://github.com/escusado/cadmium"</span>,
<span class="string">"forkColor"</span> : <span class="string">"orange"</span>,
<span class="string">"favicon"</span> : <span class="string">"assets/img/favicon.gif"</span>,
<span class="string">"icon"</span> : <span class="string">"assets/img/icon.png"</span>
}
</code></pre></div>
<p>One cool thing is that if you add entries to this file, they will be peresent into the <a href="#proj">Cd.proj Api</a>.</p>
<h4 id="assets-file"><i class="icon icon-file"></i> /assets.json</h4>
<p>This file will contain the css, js, <a href="http://www.google.com/fonts/">Google fonts</a> and any CDN file you need to load on your page:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n{\n &dqu;cdn&dqu;: [\n &dqu;<script src=&squ;http://code.jquery.com/jquery-1.10.1.min.js&squ;></script>&dqu;\n ],\n\n &dqu;css&dqu; : [\n &dqu;vendor/highlight/monokai.css&dqu;,\n &dqu;reset.css&dqu;,\n &dqu;style.css&dqu;\n ],\n\n &dqu;js&dqu; : [\n &dqu;vendor/neon.js&dqu;,\n &dqu;app/myScriptFile.js&dqu;,\n ],\n\n &dqu;googleFonts&dqu; : [\n &dqu;Montserrat:400,700&dqu;\n ]\n}\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="javascript">
{
<span class="string">"cdn"</span>: [
<span class="string">"<script src='http://code.jquery.com/jquery-1.10.1.min.js'></script>"</span>
],
<span class="string">"css"</span> : [
<span class="string">"vendor/highlight/monokai.css"</span>,
<span class="string">"reset.css"</span>,
<span class="string">"style.css"</span>
],
<span class="string">"js"</span> : [
<span class="string">"vendor/neon.js"</span>,
<span class="string">"app/myScriptFile.js"</span>,
],
<span class="string">"googleFonts"</span> : [
<span class="string">"Montserrat:400,700"</span>
]
}
</code></pre></div>
<p>Then you can render them by using the <a href="#assets">Cd.renderCdn(), Cd.renderCss() and Cd.renderJs() Api calls</a>.</p>
<h2 id="style-file"><i class="icon icon-file"></i> style.css.ejs</h2>
<p>This file; as well as the <code>index.html</code> generates the <code>style.css</code> file. It contains some variables to easy color, size and font tweaking:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n//colors\nvar colors = {\n first : &squ;#669933&squ;,\n second : &squ;#ffcc00&squ;,\n third : &squ;#93C763&squ;,\n fourth : &squ;#1296ff&squ;,\n fifth : &squ;#ED0700&squ;,\n\n bodyBg : &squ;#eeeeee&squ;,\n wrapperBg : &squ;#fdfdfd&squ;,\n\n bodyText : &squ;#333333&squ;,\n\n h1 : &squ;#424242&squ;,\n desc : &squ;#969696&squ;\n};\n\n//fonts\nvar fonts = {\n /* Trebuchet-based sans serif stack */\n body : &squ;&dqu;Segoe UI&dqu;, Candara, &dqu;Bitstream Vera Sans&dqu;, &dqu;DejaVu Sans&dqu;, &dqu;Trebuchet MS&dqu;, Verdana, &dqu;Verdana Ref&dqu;, sans-serif&squ;,\n h1 : &squ;&dqu;Montserrat&dqu;, sans-serif&squ;\n};\n\n//sizes\nvar sizes = {\n wrapper : 660,\n\n h1 : 48,\n h2 : 24,\n h3 : 16,\n\n p : 14\n};\n\n//and then we use them below for the style rules\n...\na {\n font-weight : bold;\n color : <%= colors.first %>;\n}\n...\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="javascript">
<span class="comment">//colors</span>
<span class="keyword">var</span> colors = {
first : <span class="string">'#669933'</span>,
second : <span class="string">'#ffcc00'</span>,
third : <span class="string">'#93C763'</span>,
fourth : <span class="string">'#1296ff'</span>,
fifth : <span class="string">'#ED0700'</span>,
bodyBg : <span class="string">'#eeeeee'</span>,
wrapperBg : <span class="string">'#fdfdfd'</span>,
bodyText : <span class="string">'#333333'</span>,
h1 : <span class="string">'#424242'</span>,
desc : <span class="string">'#969696'</span>
};
<span class="comment">//fonts</span>
<span class="keyword">var</span> fonts = {
<span class="comment">/* Trebuchet-based sans serif stack */</span>
body : <span class="string">'"Segoe UI", Candara, "Bitstream Vera Sans", "DejaVu Sans", "Trebuchet MS", Verdana, "Verdana Ref", sans-serif'</span>,
h1 : <span class="string">'"Montserrat", sans-serif'</span>
};
<span class="comment">//sizes</span>
<span class="keyword">var</span> sizes = {
wrapper : <span class="number">660</span>,
h1 : <span class="number">48</span>,
h2 : <span class="number">24</span>,
h3 : <span class="number">16</span>,
p : <span class="number">14</span>
};
<span class="comment">//and then we use them below for the style rules</span>
...
a {
font-weight : bold;
color : <span class="xml"><span class="vbscript"><%= colors.first %></span>;</span>
}
...
</code></pre></div>
<p>I recomend using a separate css file for your page specific rules.</p>
<!-- Api -->
<h1><i class="icon icon-gears api-icon"></i> API</h1>
<p>Usage for the <code>Cd</code> context API:</p>
<h3 id="proj">Cd.proj.<i>attrib</i></h3>
<p>As mentioned before, the <a href="#project-file">project.json file</a> contains the attributes used by the API:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<!-- views/header.ejs -->\n<div class=&dqu;header&dqu;>\n <a href=&dqu;<%= Cd.proj.url %>&dqu;>\n <img class=&dqu;tm-icon&dqu; src=&dqu;<%= Cd.proj.icon %>&dqu; alt=&dqu;<%= Cd.proj.name %>&dqu;>\n <div class=&dqu;name&dqu;><%= Cd.proj.name %><span>.<%= Cd.proj.lang %></span></div>\n <div class=&dqu;description&dqu;><%= Cd.proj.desc %></div>\n </a>\n</div>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="comment"><!-- views/header.ejs --></span>
<span class="tag"><<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"header"</span>></span>
<span class="tag"><<span class="title">a</span> <span class="attribute">href</span>=<span class="value">"<%= Cd.proj.url %>"</span>></span>
<span class="tag"><<span class="title">img</span> <span class="attribute">class</span>=<span class="value">"tm-icon"</span> <span class="attribute">src</span>=<span class="value">"<%= Cd.proj.icon %>"</span> <span class="attribute">alt</span>=<span class="value">"<%= Cd.proj.name %>"</span>></span>
<span class="tag"><<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"name"</span>></span><span class="vbscript"><%= Cd.proj.name %></span><span class="tag"><<span class="title">span</span>></span>.<span class="vbscript"><%= Cd.proj.lang %></span><span class="tag"></<span class="title">span</span>></span><span class="tag"></<span class="title">div</span>></span>
<span class="tag"><<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"description"</span>></span><span class="vbscript"><%= Cd.proj.desc %></span><span class="tag"></<span class="title">div</span>></span>
<span class="tag"></<span class="title">a</span>></span>
<span class="tag"></<span class="title">div</span>></span>
</code></pre></div>
<h3 id="assets">Assets api</h3>
<p>As mentioned before, the <a href="#assets-file">assets</a> have an special shortcut api. The assets.json will hold the assets so the api can render them using the Cd api:</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<head>\n <meta charset=&dqu;UTF-8&dqu;>\n <title><%= Cd.proj.name %>.<%= Cd.proj.lang %></title>\n <!-- favicon -->\n <link rel=&dqu;icon&dqu; type=&dqu;image/gif&dqu; href=&dqu;<%= Cd.proj.favicon+Cd.rId %>&dqu; />\n <!-- cdn -->\n <%= Cd.renderCdn() %>\n <!-- css -->\n <%= Cd.renderCss() %>\n <!-- fonts -->\n <%= Cd.renderGoogleFonts() %>\n <!-- js -->\n <%= Cd.renderJs() %>\n</head>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="tag"><<span class="title">head</span>></span>
<span class="tag"><<span class="title">meta</span> <span class="attribute">charset</span>=<span class="value">"UTF-8"</span>></span>
<span class="tag"><<span class="title">title</span>></span><span class="vbscript"><%= Cd.proj.name %></span>.<span class="vbscript"><%= Cd.proj.lang %></span><span class="tag"></<span class="title">title</span>></span>
<span class="comment"><!-- favicon --></span>
<span class="tag"><<span class="title">link</span> <span class="attribute">rel</span>=<span class="value">"icon"</span> <span class="attribute">type</span>=<span class="value">"image/gif"</span> <span class="attribute">href</span>=<span class="value">"<%= Cd.proj.favicon+Cd.rId %>"</span> /></span>
<span class="comment"><!-- cdn --></span>
<span class="vbscript"><%= Cd.renderCdn() %></span>
<span class="comment"><!-- css --></span>
<span class="vbscript"><%= Cd.renderCss() %></span>
<span class="comment"><!-- fonts --></span>
<span class="vbscript"><%= Cd.renderGoogleFonts() %></span>
<span class="comment"><!-- js --></span>
<span class="vbscript"><%= Cd.renderJs() %></span>
<span class="tag"></<span class="title">head</span>></span>
</code></pre></div>
<h3 id="code-blocks">Cd.printCode</h3>
<p>Cd uses <a target="_blank" href="http://softwaremaniacs.org/soft/highlight/en/">highlight.js</a> to highlight code, you need to pass the code as a <a href="https://help.github.com/articles/github-flavored-markdown">Github flavored Markdown</a> format using any of the <a href="http://softwaremaniacs.org/media/soft/highlight/test.html">supported highlight.js</a> formats:</p>
<div class="code-highlight">
<pre>
<code>
<%= Cd.printCode( function(){ %>
```javascript
var myCode = 'nice eyebrows!'
```
<% }) %>
</code>
</pre>
</div>
<p>You can customize which theme to use by changing the <code>"vendor/highlight/monokai.css"</code> in the <code>assets.json</code> file fo the one you like.</p>
<h3 id="render">Cd.render</h3>
<p>The render Api call lets you use partials, so you can separate your views in smaller files The api will look for your partials in the <code>/views</code> folder:</p>
<p><i class="icon icon-file"></i> <strong>views/header.ejs</strong></p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<span>This is my header!</span>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="tag"><<span class="title">span</span>></span>This is my header!<span class="tag"></<span class="title">span</span>></span>
</code></pre></div>
<p><i class="icon icon-file"></i> <strong>views/index.ejs</strong></p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<div class=&dqu;header&dqu;>\n <%= Cd.render(&squ;header.ejs&squ;) %>\n</div>\n\n<!-- Renders -->\n<div class=&dqu;header&dqu;><span>This is my header!</span></div>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="tag"><<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"header"</span>></span>
<span class="vbscript"><%= Cd.render(<span class="comment">'header.ejs') %></span></span>
<span class="tag"></<span class="title">div</span>></span>
<span class="comment"><!-- Renders --></span>
<span class="tag"><<span class="title">div</span> <span class="attribute">class</span>=<span class="value">"header"</span>></span><span class="tag"><<span class="title">span</span>></span>This is my header!<span class="tag"></<span class="title">span</span>></span><span class="tag"></<span class="title">div</span>></span>
</code></pre></div>
<h3>Cd.noCache</h3>
<p>Creates a <code>?nocache=1234</code> string containing 4 char hash, this helps if your broser has cache issues for images an assets.</p>
<div class="code-highlight"> <div class="button code-copy" data-clipboard-text="\n<link rel=&dqu;icon&dqu; type=&dqu;image/gif&dqu; href=&dqu;<%= Cd.proj.favicon + Cd.rId %>&dqu; />\n\n<!-- Renders -->\n<link rel=&dqu;icon&dqu; type=&dqu;image/gif&dqu; href=&dqu;assets/img/favicon.gif%nocache=49d8&dqu;>\n\n" ><i class="icon icon-copy"></i><div class="label">copy</div><div class="shade"></div></div> <pre><code class="django">
<span class="tag"><<span class="title">link</span> <span class="attribute">rel</span>=<span class="value">"icon"</span> <span class="attribute">type</span>=<span class="value">"image/gif"</span> <span class="attribute">href</span>=<span class="value">"<%= Cd.proj.favicon + Cd.rId %>"</span> /></span>
<span class="comment"><!-- Renders --></span>
<span class="tag"><<span class="title">link</span> <span class="attribute">rel</span>=<span class="value">"icon"</span> <span class="attribute">type</span>=<span class="value">"image/gif"</span> <span class="attribute">href</span>=<span class="value">"assets/img/favicon.gif%nocache=49d8"</span>></span>
</code></pre></div>
<!-- last notes -->
<h1>Final notes</h1>
<p>Originaly Cadmium was coded for Thulium project page, then adapted for easy page creation and fast deploy.</p>
<p>You can connect your editor to a <a href="http://livereload.com/">LiveAutoReload plugins</a> to skip the reload each time.</p>
<p>There are some things that need to be done:</p>
<ul>
<li>Clean the cadmium.js code</li>
<li>HTML shorthand helper</li>
<li>Md to HTML so you can just add your md file</li>
</ul>
<p>One simple way to do this page is to paste the HTML that Github generates for you on your repo, just tweak the code display and adjust as you need.</p>
<p>Keep in mind that Cd was coded to create this specific type of site, but surely you can adapt it to add/remove features, styles, etc.</p>
<p><a target="_blank" href="http://code.toily.mx/cadmium/">Comments welcome here</a> :)</p>
</div>
</div>
<!-- footer -->
<div class="footer">
Cadmium created by <a href="http://twitter.com/escusado">Toily</a> at <a href="http://freshout.us">Freshout</a>
<span class="cd-disclamer">
Page crafted using <a href="http://escusado.github.io/cadmium">Cadmium (Cd)</a>
</span>
</div>
</body>
</html>