Adding markdown content files for new content. Including simple test …

…file because of the difficulty with the markdown conversion.

content/en/build/data.json

@@ -0,0 +1,9 @@
+{
+	"lang" : "nglayout",
+	"title": "Front-end Code Standards & Best Practices",
+	"meta" : {
+	    "description": "Isobar's Coding Standards and Frontend development Best Practices",
+	    "keywords" : "Isobar code standards, coding standards, frontend development, frontend best practices, html code standards, html5 code standards, css code standards, best code practices, development, frontend development"
+	},
+    "return_link": "Return to Isobar"
+}

content/en/build/en.hbs

@@ -0,0 +1,8 @@
+
+<article>
+
+{{#markdown}}
+	{{md 'content/en/test.md' }}
+{{/markdown}}
+
+</article>

content/en/css.md

@@ -0,0 +1,90 @@
+<section>
+## CSS
+
+CSS is where the visual presentation logic of a website belongs. Well-written CSS makes good use of its cascading nature - general styles are applied first, and those styles are overridden for more specific instances as necessary.
+
+### Goals
+ - General coding principles
+    - Customization / Maintainabilty
+    - Components / Modules / OOCSS
+
+### Getting Started
+ - Grids
+ - Frameworks
+
+### CSS Standards
+
+#### Inclusion
+
+Use the <span class="code">&lt;link&gt;</span> tag to include all your stylesheets in the <span class="code">&lt;head&gt;</span> of the document. For optimal page performance, concatenate your CSS into as few files as possible and do not use the <span class="code">@import</span> command to include other stylesheets, as this will fire an additional HTTP request and block page rendering until its completion.
+
+```
+<link rel="stylesheet" type="text/css" href="main.css" />
+```
+
+#### Inline Styling
+
+Do not put styling information into your HTML markup directly, either with the <span class="code">style</span> attribute that accepts CSS or with deprecated attributes such as <span class="code">align</span>, <span class="code">border</span>, or <span class="code">width</span>. These are difficult to maintain and make it harder to track down what is causing an element to appear as it does.
+
+#### Formatting
+
+We put each selector on its own line and each property on its own line for easy readability and so version control systems can clearly show which parts have changed. The attributes within a selector should be alphabetized for easy scanning and so that compression algorithms like gzip have a greater chance of finding repeatable patterns.
+
+```
+#content {
+    margin-left: -2%;
+}
+.most-popular,
+.my-favorites,
+.twitter-feed {
+    float: left;
+    padding-left: 2%;
+    width: 33.3333333%;
+}
+```
+
+We do not indent child styles underneath their parent styles for a few reasons. When scanning through a CSS file to locate media queries, we generally look for indented styles, so indenting selectors that are not within a media query causes confusion. It also hinders maintainability. HTML and CSS structure can change frequently over the course of a project, quickly rendering obsolete the parent-child relationship the indentation used to represent. And the more levels of indentation there are, the harder it is to update.
+
+#### Box Model
+
+To simplify CSS authoring, we set the <span class="code">box-sizing</span> attribute to <span class="code">border-box</span> for all page elements. This enables us to use round numbers for width like 50% and then apply a padding or border to that same element without needing to (1) adjust the width accordingly using calc (since borders use pixels rather than percents) or (2) create an element inside it to take the padding and border. This is the only case where we use the inefficient universal selector (<span class="code">*</span>).
+
+```
+* {
+    -moz-box-sizing: border-box;
+    -webkit-box-sizing: border-box;
+    box-sizing: border-box;
+}
+```
+
+#### Specificity
+
+CSS is most efficient when its selectors are [extremely specific with limited DOM traversal involved](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Writing_efficient_CSS). The ID is the most specific selector, since it can only match one element, and the class is a close second. Use those whenever possible rather than HTML tag names.
+
+The descendant selector (the space character) is the most expensive selector in CSS. The child selector (the &quot;<span class="code">&gt;</span>&quot; character) is also expensive, especially when the rules are tag names rather than classes or IDs. Avoid both. Try applying a class to the element you want to target instead.
+
+```
+/* BAD */
+button#back-button { ... }
+.popular ul li a { ... }
+.popular > ul > li > a { ... }
+
+/* GOOD */
+#back-button { ... }
+.popular-link { ... }
+.popular-link { ... }
+```
+
+Avoid using the <span class="code">!important</span> keyword. Treat it like the nuclear option, only to be used in the most extreme of cases. There is usually another way to achieve the same goal without causing headaches for developers in the future who are either trying to debug a styling issue or trying to use normal specificity to override a style for a particular element only to find that they can't.
+
+### Next Steps
+ - Compatibility
+ - Internet Explorer Bugs
+ - Use CSS3
+ - Color Management
+
+### Resources
+
+Further reading on the wiki etc.
+
+</section>

content/en/general.md

@@ -0,0 +1,46 @@
+<section>
+# Front-End Code Standards
+
+## General
+
+This document contains the formatting guidelines and best practices for the front-end web development team at Isobar. There are many ways of leveraging HTML, CSS, and JavaScript to create a website - each item here represents either (1) a decision we've made favoring one method over its alternatives or (2) a reminder to follow existing standards. What this document is _not_ is a series of explanations as to how front-end technologies work; a basic familiarity is assumed. It also does _not_ provide evaluations of the pros and cons of various alternatives; we pick what we consider to be the best one and run with it. Any issues that don't yet have a clear solution are not listed here.
+
+Our motivations in creating this document are to (1) foster code consistency across our projects to facilitate ease of maintenance and onboarding and (2) educate new developers on how best to create robust, performant, and accessible websites.
+
+### Goals
+ - Consistency
+ - Professional standards
+ - Pillars of Front-end Development
+ - Architectural thinking
+
+### Getting Started
+ - Identify Deliverables
+ - Development vs Production
+ - Browser and device requirements  
+
+### General Standards
+ - Compression
+ - Maintainabilty
+ - Readability
+ - Comments
+
+(redundant below)
+
+### Formatting
+
+#### Indentation
+
+For all code languages, we use soft tabs comprised of four spaces per tab. Hitting the Tab key in your text editor should generate four space characters rather than one tab character. This results in our code appearing identical across platforms.
+
+#### Readability
+
+We encourage liberal use of whitespace, comments, and descriptive variable names as appropriate for writing easy-to-read code. There is no need to write code in an obfuscated or compressed way for the purpose of file-size savings; we will use automated server-side or build processes to concatenate, minify, and gzip all static client-side code (such as CSS and JavaScript).
+
+### Next Steps
+
+(knowledge transfer?)
+
+### Resources
+
+Further reading on the wiki
+</section>

content/en/html.md

@@ -0,0 +1,143 @@
+<section>
+## HTML
+
+HTML markup defines the content of a document and gives it a rudimentary structure such as headers, paragraphs, and lists. It provides a number of semantic constructs that allow automated tools like search engines and screen readers to make sense of the document and to understand relationships between pieces of content. A well-written HTML document will make appropriate use of these semantic elements and leave all responsibility for controlling the presentation of the document to the CSS stylesheet.
+
+### Goals
+ - Consistency
+ - Semantic Markup
+ - Validation
+
+### Getting Started
+ - Templates 
+ - Frameworks
+
+### HTML Standards
+ - HTML5 
+    - Doctype
+    - HTML5 Tags
+    - Character Encoding
+    - Validation
+ - General Markup
+ - Tags
+    - Optional
+    - Self-closing
+ - Attributes
+    - Quoted
+    - Extending HTML5
+       - Data attributes, etc
+
+#### Doctype
+
+We always include a proper doctype to trigger standards mode. Omitting the doctype triggers quirks mode and should always be avoided. The HTML5 doctype is simple and easy to remember.
+
+```
+<!doctype html>
+```
+
+#### Character Encoding
+
+All markup should be delivered as UTF-8, since it has the best support for internationalization. The character encoding should be designated in both the HTTP header and the head of the document via a meta tag. If the server happens to omit the HTTP header, the browser takes a guess at the character encoding and begins parsing the markup, throwing away all that work and starting over if it encounters the meta tag and its guess was incorrect. Because of this, as a best practice, we always put the meta tag as early in the <span class="code">&lt;head&gt;</span> tag as possible.
+
+```
+<meta charset="UTF-8">
+```
+
+#### Attribute Values
+
+We use quotes to surround all attribute values in HTML, despite quotes being optional in HTML5. This maintains consistency between attribute values that contain whitespace and those that don't.
+
+```
+<form class="registration module clearfix" action="/register" method="POST">
+```
+
+#### IDs vs. Classes
+
+HTML elements can be identified by using the <span class="code">id</span> and <span class="code">class</span> attributes. An ID is a unique identifier for that particular element; no other element on the page should use the same ID. This uniqueness allows <span class="code">&lt;label&gt;</span> elements to associate themselves with a particular input and URLs to jump to a particular scroll position on a page. Classes are not unique. The same class can be used on multiple elements within a page, and a single element can have more than one class.
+
+```
+<ul id="categories">
+    <li class="category">Jackets</li>
+    <li class="category">Accessories</li>
+    <li class="category">Shoes</li>
+</ul>
+```
+
+When coming up with names for an ID or class, we use semantic names like &quot;secondary-nav&quot; or &quot;primary-button&quot; that describe what the element is, rather than names like &quot;left-nav&quot; or &quot;blue-button&quot; that describe what the element looks like, which can change over time. We also use lowercase names with hyphens separating words as opposed to camelCase or underscores. This matches the lowercase nature of HTML5 as well as the naming scheme for <span class="code">data-xxx</span> attributes.
+
+#### Use of HTML5 Elements
+
+To provide additional semantic value to our documents, we make use of HTML5 elements such as <span class="code">&lt;header&gt;</span>, <span class="code">&lt;article&gt;</span>, and <span class="code">&lt;section&gt;</span> where appropriate. However, in order to ensure that our HTML is as backwards-compatible as possible, we do not apply IDs or classes to them, since older browsers do not understand these elements by default and will not apply styling to them.
+
+```
+<header>
+    <div class="site-header">
+        ...
+    </div>
+</header>
+```
+
+#### Anchors
+
+All anchor links should point to absolute or relative URLs with user-readable content. Do not link to XML or JSON resources that are designed to be Ajaxed by JavaScript instead of navigated to directly, and do not put JavaScript in an anchor's <span class="code">href</span> attribute like &quot;<span class="code">javascript:loadPage(2);</span>&quot;. This allows search engines to index the content, allows the user to open the links in a new tab or window, and means the links will still work when JavaScript is broken, disabled, or not supported. This will require that the back-end be able to return a full HTML page for each important content state (e.g. sorting a table column).
+
+#### Paragraphs
+
+Avoid using <span class="code">&lt;br /&gt;</span> tags to separate paragraphs or lines of text. Use <span class="code">&lt;p&gt;</span> instead.
+
+#### Definition Lists
+
+We use definition lists to display a single record of name-value pairs, like a contact card.
+
+#### Tables
+
+Tables should not be used for page layout; only use them when you need to display tabular data. They provide an important semantic association (used mostly by screen readers for the sight-impaired) between row/column headers and their data, so use <span class="code">&lt;table&gt;</span> rather than other elements when displaying multiple records of data.
+
+The <span class="code">&lt;caption&gt;</span> element is the recommended way to describe a table for both sighted and sight-impaired users, though this can also be done less semantically in the normal page text around the table. We use the <span class="code">&lt;thead&gt;</span> and <span class="code">&lt;tbody&gt;</span> elements to denote which row contains column headers so when a user prints the website and the table runs onto another page, browsers can display the <span class="code">&lt;thead&gt;</span> on each page for easier readability. Remember to use the <span class="code">scope</span> attribute on the <span class="code">&lt;th&gt;</span> element to indicate whether the header applies to the row or column.
+
+```
+<table>
+    <caption>First two U.S. presidents</caption>
+    <thead>
+        <tr>
+            <th scope="col">Name</th>
+            <th scope="col">Took office</th>
+            <th scope="col">Party</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>George Washington</td>
+            <td>April 30, 1789</td>
+            <td>n/a</td>
+        </tr>
+        <tr>
+            <td>John Adams</td>
+            <td>March 4, 1797</td>
+            <td>Federalist</td>
+        </tr>
+    </tbody>
+</table>
+```
+
+#### Forms
+
+For both semantic and functional reasons, we make full use of the <span class="code">&lt;form&gt;</span> tag for all sections requiring user input. All form <span class="code">action</span> attributes should point to URLs with user-readable content, so they will still work if the form is submitted by the user before JavaScript has loaded on a page, or if JavaScript is broken, disabled, or not supported. This will require that the back-end be able to return a full HTML page for form submission (e.g. registering a new user, editing the quantity in a shopping cart).
+
+#### Input Labels
+
+All input fields should be associated with a <span class="code">&lt;label&gt;</span> element. The <span class="code">for</span> attribute of the <span class="code">&lt;label&gt;</span> element should contain the ID of the corresponding input field. This means the input field will receive focus when a user clicks the label and also enables screen readers for sight-impaired users to read out an appropriate description of the input field.
+
+```
+<label for="home-address">Home Address</label>
+<input id="home-address" type="text" />
+```
+
+### Next Steps
+ - Templates
+ - Break down (CMS, templates, re-use)
+
+### Resources
+Further information on the wiki...
+
+</section>

content/en/javascript.md

@@ -0,0 +1,60 @@
+<section>
+## JavaScript
+
+### Goals
+
+### Getting Started
+ - JavaScript Libraries
+
+### JavaScript Standards
+
+#### Inclusion
+
+Use the <span class="code">&lt;script&gt;</span> tag to include your JavaScript files at the bottom of your HTML document just before the closing <span class="code">&lt;/body&gt;</span> tag. For optimal page performance, concatenate your JavaScript into as few files as possible.
+
+```
+<script type="text/javascript" src="main.js"></script>
+```
+
+#### Formatting
+
+The use of whitespace should follow long-standing English writing conventions. Specifically, each comma and colon (and semi-colons that don't end a line) should be followed by a single space. Binary and ternary operators should have a single space on each side. There should be no space characters between parentheses and their contents. Opening braces should appear on the same line as their preceding argument.
+
+```
+for (var i = 0, len = arr.length; i < len; i++) {
+    // do something
+}
+```
+
+To maximize readability without worrying about which boolean operators bind more tightly than others, each segment of a boolean expression should be enclosed in parentheses.
+
+```
+if ((allowUpdate) && ((user.isAdmin) || (user.role === item.owner))) {
+    // do something
+}
+```
+
+#### Variable Declaration
+
+To avoid confusion between global and local variables, we declare each variable on its own line with the <span class="code">var</span> keyword. We do not use a single <span class="code">var</span> keyword and then chain several variable declarations onto it separated by a comma.
+
+```
+var currentVal = $(this).val();
+var min = parseInt($(this).attr('min'), 10);
+var max = parseInt($(this).attr('max'), 10);
+```
+
+#### Feature Detection
+
+Always test for the existence of a browser API, function, or object property before you use it, and make sure the user experience is still functional (to the extent possible) if it's not found. We rely on JavaScript-based feature detection rather than server-side device detection because it's more robust, easily maintained, and future-proof.
+
+### Next Steps
+ - Debugging
+ - Patterns for Better JavaScript
+ - Unit Testing
+ - Node.js
+
+### Resources
+ - Links to wiki, etc.
+
+</section>

content/en/performance.md

@@ -0,0 +1,19 @@
+<section>
+## Performance
+
+### Goals
+... 
+
+### Getting Started
+...
+
+### Standards
+...
+
+### Next Steps
+...
+
+### Resources
+
+</section>
+