What is it?
Cadmium (Cd) 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 Github Pages.
Features
- Configurable styles
- Json data api
- Highlighted code blocks
- Partials support
- Preview app with express.js
Usage
//1. Get Cadmium files into your gh-pages branch
> ls
.gitignore
assets
views
assets.json
package.json
project.json
cadmium.js
//2. Get the dependencies
> npm install
//3. Run Cadmium server
> node cadmium.js
Cd ready on port: 3000
//Visit http://localhost:3000
Parsing project.json
Parsing assets.json
Creating context.
Rendering style and index file!
index.html File saved!
Cd will generate the index.html each time you reload your browser. This is the file that Github Pages displays.
Tweak it!
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 :)
How it works?
Cd has a very simple json and template system, it uses Thulium implementation of EJS to compile its views.
/views
The views are stored into the views folder, Cd by default will look for views/index.ejs to render it, so start there, you can use partials to organize your views.
EJS
Cd uses EJS for the templates, we are using the Thulium flavor syntax:
<!-- Execute code -->
<% var myVariable = "This IS MY VariablE" %>
<!-- print values -->
<div><%= myVariable.toLowercase() %></div>
<!-- Renders -->
<div>this is my variable</div>
Config files
Cd uses 2 json files to work:
/project.json
This json file will hold your project data, Cd uses this values to render them in the views:
{
"name" : "Cadmium",
"lang" : "js",
"desc" : "A simple theme for your project",
"url" : "http://escusado.github.io/cadmium",
"githubUrl" : "https://github.com/escusado/cadmium",
"forkColor" : "orange",
"favicon" : "assets/img/favicon.gif",
"icon" : "assets/img/icon.png"
}
One cool thing is that if you add entries to this file, they will be peresent into the Cd.proj Api.
/assets.json
This file will contain the css, js, Google fonts and any CDN file you need to load on your page:
{
"cdn": [
"<script src='http://code.jquery.com/jquery-1.10.1.min.js'></script>"
],
"css" : [
"vendor/highlight/monokai.css",
"reset.css",
"style.css"
],
"js" : [
"vendor/neon.js",
"app/myScriptFile.js",
],
"googleFonts" : [
"Montserrat:400,700"
]
}
Then you can render them by using the Cd.renderCdn(), Cd.renderCss() and Cd.renderJs() Api calls.
style.css.ejs
This file; as well as the index.html is generated each page reload this generates the final style.css. It contains some variables to easy color, size and font tweaking:
//colors
var colors = {
first : '#669933',
second : '#ffcc00',
third : '#93C763',
fourth : '#1296ff',
fifth : '#ED0700',
bodyBg : '#eeeeee',
wrapperBg : '#fdfdfd',
bodyText : '#333333',
h1 : '#424242',
desc : '#969696'
};
//fonts
var fonts = {
/* Trebuchet-based sans serif stack */
body : '"Segoe UI", Candara, "Bitstream Vera Sans", "DejaVu Sans", "Trebuchet MS", Verdana, "Verdana Ref", sans-serif',
h1 : '"Montserrat", sans-serif'
};
//sizes
var sizes = {
wrapper : 660,
h1 : 48,
h2 : 24,
h3 : 16,
p : 14
};
//and the used in below for the style rules
...
a {
font-weight : bold;
color : <%= colors.first %>;
}
...
I recomend using a separate css file for your page specific rules.
API
Usage for the Cd context API:
Cd.proj.attrib
As mentioned before, the project.json file contains the attributes used by the API:
<!-- views/header.ejs -->
<div class="header">
<a href="<%= Cd.proj.url %>">
<img class="tm-icon" src="<%= Cd.proj.icon %>" alt="<%= Cd.proj.name %>">
<div class="name"><%= Cd.proj.name %><span>.<%= Cd.proj.lang %></span></div>
<div class="description"><%= Cd.proj.desc %></div>
</a>
</div>
Assets api
As mentioned before, the assets have an special shortcut api. The assets.json will hold the assets so the api can render them using the Cd api:
<head>
<meta charset="UTF-8">
<title><%= Cd.proj.name %>.<%= Cd.proj.lang %></title>
<!-- favicon -->
<link rel="icon" type="image/gif" href="<%= Cd.proj.favicon+Cd.rId %>" />
<!-- cdn -->
<%= Cd.renderCdn() %>
<!-- css -->
<%= Cd.renderCss() %>
<!-- fonts -->
<%= Cd.renderGoogleFonts() %>
<!-- js -->
<%= Cd.renderJs() %>
</head>
Cd.printCode
Cd uses highlight.js to highlight code, you need to pass the code as a Github flavored Markdown format using any of the supported highlight.js formats:
<%= Cd.printCode( function(){ %>
```javascript
var myCode = 'nice eyebrows!'
```
<% }) %>
You can customize which theme to use by changing the "vendor/highlight/monokai.css" in the assets.json file fo the one you like.
Cd.render
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 /views folder:
views/header.ejs
<span>This is my header!</span>
views/index.ejs
<div class="header">
<%= Cd.render('header.ejs') %>
</div>
<!-- Renders -->
<div class="header"><span>This is my header!</span></div>
Cd.noCache
Creates a ?nocache=1234 string containing 4 char hash, this helps if your broser has cache issues for images an assets.
<link rel="icon" type="image/gif" href="<%= Cd.proj.favicon + Cd.rId %>" />
<!-- Renders -->
<link rel="icon" type="image/gif" href="assets/img/favicon.gif%nocache=49d8">
Final notes
Originaly Cadmium was coded for Thulium project page, then adapted for easy page creation and fast deploy.
You can connect your editor to a LiveAutoReload plugins to skip the reload each time.
There are some things that need to be done:
- Clean the cadmium.js code
- HTML shorthand helper
- Md to HTML so you can just add your md file
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.
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.