Fork me on GitHub
A simple Code documentation theme for your project

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.

Get the code on Github!




//1. Get Cadmium files into your gh-pages branch
> ls

//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.


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.


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:


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"       : "",
  "githubUrl" : "",
  "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.


This file will contain the css, js, Google fonts and any CDN file you need to load on your page:


  "cdn": [
    "<script src=''></script>"

  "css" : [

  "js" : [

  "googleFonts" : [

Then you can render them by using the Cd.renderCdn(), Cd.renderCss() and Cd.renderJs() Api calls.


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:


var colors = {
  first  : '#669933',
  second : '#ffcc00',
  third  : '#93C763',
  fourth : '#1296ff',
  fifth  : '#ED0700',

  bodyBg    : '#eeeeee',
  wrapperBg : '#fdfdfd',

  bodyText  : '#333333',

  h1   : '#424242',
  desc : '#969696'

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'

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.


Usage for the Cd context API:


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="<%= %>">
    <div class="name"><%= %><span>.<%= Cd.proj.lang %></span></div>
    <div class="description"><%= Cd.proj.desc %></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:


    <meta charset="UTF-8">
    <title><%= %>.<%= 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() %>


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(){ %>
    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.


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:



<span>This is my header!</span>



<div class="header">
    <%= Cd.render('header.ejs') %>

<!-- Renders -->
<div class="header"><span>This is my header!</span></div>


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:

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.

Comments welcome here :)