Skip to content

Commit

Permalink
Escape inline code examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@rcherny
rcherny committed Jun 7, 2014
1 parent a1860b5 commit 041f583
Show file tree
Hide file tree
Showing 3 changed files with 17 additions and 17 deletions.
10 changes: 5 additions & 5 deletions content/en/css.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ CSS is where the visual presentation logic of a website belongs. Well-written CS

#### 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.
Use the `<link>` tag to include all your stylesheets in the `<head>` of the document. For optimal page performance, concatenate your CSS into as few files as possible and do not use the `@import` 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.
Do not put styling information into your HTML markup directly, either with the `style` attribute that accepts CSS or with deprecated attributes such as `align`, `border`, or `width`. These are difficult to maintain and make it harder to track down what is causing an element to appear as it does.

#### Formatting

Expand All @@ -47,7 +47,7 @@ We do not indent child styles underneath their parent styles for a few reasons.

#### 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>).
To simplify CSS authoring, we set the `box-sizing` attribute to `border-box` 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 (`*`).

```
* {
Expand All @@ -61,7 +61,7 @@ To simplify CSS authoring, we set the <span class="code">box-sizing</span> attri

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.
The descendant selector (the space character) is the most expensive selector in CSS. The child selector (the &quot;`>`&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 */
Expand All @@ -75,7 +75,7 @@ button#back-button { ... }
.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.
Avoid using the `!important` 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
Expand Down
20 changes: 10 additions & 10 deletions content/en/html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ We always include a proper doctype to trigger standards mode. Omitting the docty

#### 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.
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 `<head>` tag as possible.

```
<meta charset="UTF-8">
Expand All @@ -53,7 +53,7 @@ We use quotes to surround all attribute values in HTML, despite quotes being opt

#### 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.
HTML elements can be identified by using the `id` and `class` 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 `<label>` 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">
Expand All @@ -63,11 +63,11 @@ HTML elements can be identified by using the <span class="code">id</span> and <s
</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.
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 `data-xxx` 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.
To provide additional semantic value to our documents, we make use of HTML5 elements such as `<header>`, `<article>`, and `<section>` 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>
Expand All @@ -79,21 +79,21 @@ To provide additional semantic value to our documents, we make use of HTML5 elem

#### 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).
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 `href` attribute like `javascript:loadPage(2);`. 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.
Avoid using `<br />` tags to separate paragraphs or lines of text. Use `<p>` 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.
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 `<table>` 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.
The `<caption>` 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 `<thead>` and `<tbody>` 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 `<thead>` on each page for easier readability. Remember to use the `scope` attribute on the `<th>` element to indicate whether the header applies to the row or column.

```
<table>
Expand Down Expand Up @@ -122,11 +122,11 @@ The <span class="code">&lt;caption&gt;</span> element is the recommended way to

#### 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).
For both semantic and functional reasons, we make full use of the `<form>` tag for all sections requiring user input. All form `action` 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.
All input fields should be associated with a `<label>` element. The `for` attribute of the `<label>` 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>
Expand Down
4 changes: 2 additions & 2 deletions content/en/javascript.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

#### 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.
Use the `<script>` tag to include your JavaScript files at the bottom of your HTML document just before the closing `</body>` tag. For optimal page performance, concatenate your JavaScript into as few files as possible.

```
<script type="text/javascript" src="main.js"></script>
Expand All @@ -36,7 +36,7 @@ if ((allowUpdate) && ((user.isAdmin) || (user.role === item.owner))) {

#### 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.
To avoid confusion between global and local variables, we declare each variable on its own line with the `var` keyword. We do not use a single `var` keyword and then chain several variable declarations onto it separated by a comma.

```
var currentVal = $(this).val();
Expand Down

0 comments on commit 041f583

Please sign in to comment.