Making modifications to CoApp website

Requirements

You need to make sure that you've checked out the website source code, and can run the site generator.

Website Project Layout

The CoApp website project is built using a static-site generator called DocPad, written in coffee-script (which actually uses node.js and runs as JavaScript).

The generator (along with node.js) is entirely contained within the project, so no additional tools are needed.

The project as a whole is laid out in the following form:

├───documentation                   // documentation for components used to build the website
│   └───bootstrap                   // documentation for bootstrap (the base css layout we use)
├───node_modules                    // the node.js modules that make up the DocPad system
│   ├───coappcms                    // nearly all the custom work in docpad for CoApp is here
│   ├───coffee-script               
│   ├───docpad
│   ├───ejs                         // ejs is the javascript templating engine (when you see .html.ejs)
│   ├───enumerable                  // a linq-like library for javascript. 
│   ├───express
│   ├───github-flavored-markdown    // the basis for the markdown support (the rest is in coappcms)
│   └───MD5                         
├───out                             // the output of the generate command dumps in here
├───plugins                         // DocPad plugin modules (in coffee-script, ew!)
│   ├───coappmarkdown               // the skeleton plugin (real guts are in coappcms above)
│   ├───ejs 
│   └───totaldocuments
├───src                             // the website content (see below)
└───tools                           // the binary tools needed to generate the site (node.js, etc)

Unless you plan on making changes to DocPad itself, most of that isn't of much concern.

The "source code" to the website content is all contained in the src folder.

Website Content Layout

The overall layout of the src folder is as follows:

src
├───dynamic                         // all the dynamic content in the website is under here
│   │
│   ├───developers                  // developer pages
│   ├───help                        // help pages
│   ├───news                        // blog posts
│   ├───pages                       // top-level pages
│   ├───reference                   // reference pages
│   ├───scripts                     // client side javascript files that are transformed before sent out
│   └───styles                      // css (.less to .css) files -- all style info in heree
│       └───bootstrap               // bootstrap css files
│
├───includes                        // these are small templates that can be included in multiple pages.
├───layouts                         // these contain the layouts for all the pages in the site
└───static                          // all static content (things that don't change at generation time) are here
    ├───images                      // image files go in here
    │   ├───blog
    │   ├───Flags
    │   ├───player
    │   ├───social
    │   └───tutorials
    ├───scripts                     // client-side javascript
    │   └───bootstrap               // bootstrap client-side scripts
    └───styles                      // static css files

The website content is essentially composed of 4 parts:

Static Content

The static content of the website is just that--files that are copied verbatim without modification to the final website. Images, client-side-scripts and some CSS can be found in this section.

All of the static content is copied as a tree into the root of the target website.

Dynamic Content

The dynamic content of the website consists of files that are transfomed in one way or another. The transformation they go thru is specified by the extensions that a given file has. Reading from the end of the file backwards, you can see the transformations a given file will go thru.

For example, a file named index.html.md.ejs will go from an ejs(embedded javascript template) file to md (markdown) and finally html . DocPad will run the different transformers on the file as it makes its way thru the pipeline.

Before the content is transformed, there is an optional section at the top of any text file called the "Front Matter", in a format called yaml. You can think of the front matter as the ability to set some variables for the page before it makes its journey thru the transformation pipeline.

The different formats that are generally used in CoApp's Website are:

Layouts

TODO : Layouts are how the content is stuffed into pages. For now, if you need to know, ask.

Includes

TODO : Includes are common boxes that go in the side areas (kinda like mini-content) For now, if you need to know, ask.

YAML Front matter

Each file can declare some values that are passed to the transformation pipeline.

YAML must always appear at the very beginning of the file, and always starts and ends with triple-dash (---) on a line by iself:

---
layout: 'article'
title: 'Modifying the CoApp Website'
version: 1.0
docid: 'developer:modifywebsite'
---

Garrett-Flavored Markdown Guide

Visit the guide for Garrett Flavored Markdown

Falling back to HTML

Markdown (specifically garrett-flavored-markdown ) doesn't cover all the formatting that is required to build a website, so occasionally we have to fall back to using plain old HTML.

We do however, have an excellent CSS layout foundation provided by bootstrap, so most of what we need is pretty trivial to do.

Tables

Markdown doesn't have any support for tables, other than they embed them just fine.
The content in a table must be HTML too--markdown doesn't process inside of tables.

Use the following template for laying out tables:

<table class="zebra-striped" >
    <thead><tr>
        <th>Column1 Header</th>
        <th>Column2 Header</th>
        <th>Column3 Header</th>
    </tr></thead>
    <tbody>
        <tr>
            <td>text</td>
            <td>text</td>
            <td>text</td>
        </tr>
        <tr>
            <td>text2</td>
            <td>text2</td>
            <td>text2</td>
        </tr>
    </tbody>
</table>

Which will render a table that looks like:

Labels

Bootstrap provides excellent label support:

Alert Messages

Bootstrap supports alert messages that you can use in paragraph blocks with class="alert-message" class declaration (along with an optional success, warning, error, or info)

<p class="alert-message error">
    Danger! This is important! See? You Looked?
</p>

Renders as :

Danger! This is important! See? You Looked?

Block Messages

Bootstrap also gives us very nice block messages-- You can use paragraph blocks with class="alert-message block-message" class declaration (along with an optional success, warning, error, or info)

<p class="alert-message block-message success">
    This message shows something important that you should consider ... 
</p>

Renders as:

This message shows something important that you should consider ...