Making modifications to CoApp website
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 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:
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
Website Content Layout
The overall layout of the
src folder is as follows:
The website content is essentially composed of 4 parts:
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.
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
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:
|.md||Markdown||The CoApp website uses a variant of markdown called garrett-flavored-markdown, which itself is a variant of GitHub-Flavored-Markdown.|
|.less||Lesscss - dynamic css||You can learn more about lesscss at it's website: http://lesscss.org/|
|.styl||Stylus -- "Expressive CSS"||Only used in one file, but you can find out more: http://learnboost.github.com/stylus/docs/executable.html|
TODO : Layouts are how the content is stuffed into pages. For now, if you need to know, ask.
TODO : Includes are common boxes that go in the side areas (kinda like mini-content) For now, if you need to know, ask.
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 Variable||Pages Used||Purpose|
|layout||All Pages||Determines what template (or chain of templates, as a layout template can refer to another) is used for the page.|
|title||All Pages||The 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.|
|version||Articles||Article 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)|
|docid||All Pages||Pages can set their docid so that they can use GFM reference links instead of linking to the physical filename|
|order||Top level pages (ones in the ||Order determines what order the pages appear in the top navigation bar.|
|rightsideboxes, leftsideboxes||All Pages*||Pages can declare 'included' boxes on the left and right side of content|
|author||News posts (blog)||Blog posts specify the post author.|
|News posts (blog)||Blog posts link to the twitter id of the author if specified|
|tags||News posts (blog)||for tagging blog posts.|
Visit the guide for [Garrett Flavored Markdown][gfm]
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.
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|
Bootstrap provides excellent label support:
Bootstrap supports alert messages that you can use in paragraph blocks with
class="alert-message" class declaration (along with an optional
<p class="alert-message error"> Danger! This is important! See? You Looked? </p>
Renders as :
Danger! This is important! See? You Looked?
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
<p class="alert-message block-message success"> This message shows something important that you should consider ... </p>
This message shows something important that you should consider ...