Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
280 lines (231 sloc) 11.9 KB
layout title version docid
article
Making modifications to CoApp website
1.0
developer:modifywebsite

Requirements

You need to make sure that you've [checked out the website source code][developer:checkoutwebsite], 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:

ExtensionFormatDetails
.ejsEmbedded Javascript TemplateThe actual EJS library used is from https://github.com/visionmedia/ejs , however the documentation at the site http://embeddedjs.com/ may be useful for understanding
.mdMarkdownThe CoApp website uses a variant of markdown called garrett-flavored-markdown, which itself is a variant of GitHub-Flavored-Markdown.
.lessLesscss - dynamic cssYou can learn more about lesscss at it's website: http://lesscss.org/
.stylStylus -- "Expressive CSS"Only used in one file, but you can find out more: http://learnboost.github.com/stylus/docs/executable.html
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'
---
Header VariablePages UsedPurpose
layoutAll PagesDetermines what template (or chain of templates, as a layout template can refer to another) is used for the page.
titleAll PagesThe title is used by the master layout page to set the HMTL title, as well as for metadata in the headers for things like facebook integration.
versionArticlesArticle pages can set a version. If the version number changes, the disqus comment thread ID gets changed, and starts a new thread. (this makes it so we can 'dump' old threads when they cease to be relevant)
docidAll PagesPages can set their docid so that they can use GFM reference links instead of linking to the physical filename
orderTop level pages (ones in the src/dynamic/pages folder)Order determines what order the pages appear in the top navigation bar.
rightsideboxes, leftsideboxesAll Pages*Pages can declare 'included' boxes on the left and right side of content
authorNews posts (blog)Blog posts specify the post author.
twitterNews posts (blog)Blog posts link to the twitter id of the author if specified
tagsNews posts (blog)for tagging blog posts.

Garrett-Flavored Markdown Guide

Visit the guide for [Garrett Flavored Markdown][gfm]

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:

Column1 Header Column2 Header Column3 Header
text text text
text2 text2 text2

Labels

Bootstrap provides excellent label support:

Label Result
<span class="label">Default</span> Default
<span class="label success">New</span> New
<span class="label warning">Warning</span> Warning
<span class="label important">Important</span> Important
<span class="label notice">Notice</span> Notice

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