Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/necolas/idiomatic-html
Principles of writing consistent, idiomatic HTML.
https://github.com/necolas/idiomatic-html
Last synced: 3 months ago
JSON representation
Principles of writing consistent, idiomatic HTML.
- Host: GitHub
- URL: https://github.com/necolas/idiomatic-html
- Owner: necolas
- Created: 2012-05-25T20:31:32.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2015-12-26T21:07:03.000Z (almost 9 years ago)
- Last Synced: 2024-06-03T09:45:08.219Z (5 months ago)
- Homepage:
- Size: 15.6 KB
- Stars: 525
- Watchers: 43
- Forks: 67
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Principles of writing consistent, idiomatic HTML
The following document outlines a reasonable style guide for HTML development.
These guidelines strongly encourage the use of existing, common, sensible
patterns. They should be adapted as needed to create your own style guide.
This is a living document and new ideas are always welcome. Please
contribute.
## Table of contents
1. [General principles](#general-principles)
2. [Whitespace](#whitespace)
3. [Format](#format)
4. [Attribute order](#attribute-order)
5. [Naming](#naming)
6. [Practical example](#example)
[License](#license)
* All code in any code-base should look like a single person typed it, no
matter how many people contributed.
* Strictly enforce the agreed upon style.
* If in doubt when deciding upon a style, use existing, common patterns.
Only one style should exist across the entire source of your code-base. Always
be consistent in your use of whitespace. Use whitespace to improve
readability.
* Never mix spaces and tabs for indentation.
* Choose between soft indents (spaces) or real tabs. Stick to your choice
without fail. (Preference: spaces)
* If using spaces, choose the number of characters used per indentation level.
(Preference: 4 spaces)
Tip: configure your editor to "show invisibles". This will allow you to
eliminate end of line whitespace, eliminate unintended blank line whitespace,
and avoid polluting commits.
* Always use lowercase tag and attribute names.
* Write one discrete element per line.
* Use one additional level of indentation for each nested element.
* Use valueless boolean attributes (e.g. `checked` rather than
`checked="checked"`).
* Always use double quotes to quote attribute values.
* Omit the `type` attributes from `link` stylesheet, `style` and `script`
elements.
* Always include closing tags.
* Don't include a trailing slash in self-closing elements.
(Keep line-length to a sensible maximum, e.g., 80 columns.)
Example:
```html
[tweet text]
Reply
```
### Exceptions and slight deviations
Elements with multiple attributes can have attributes arranged across multiple
lines in an effort to improve readability and produce more useful diffs.
Example:
```html
[text]
```
HTML attributes should be listed in an order that reflects the fact that class
names are the primary interface through which CSS and JavaScript select
elements.
1. `class`
2. `id`
3. `data-*`
4. Everything else
Example:
````html
[text]
````
Naming is hard, but very important. It's a crucial part of the process of
developing a maintainable code base, and ensuring that you have a relatively
scalable interface between your HTML and CSS/JS.
* Use clear, thoughtful, and appropriate names for HTML classes. The names
should be informative both within HTML and CSS files.
* Avoid _systematic_ use of abbreviated class names. Don't make things
difficult to understand.
Example with bad names:
```html
```
```css
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
```
Example with better names:
```html
```
```css
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
```
An example of various conventions.
```html
Document
[text]
```
_Principles of writing consistent, idiomatic HTML_ by Nicolas Gallagher is
licensed under the [Creative Commons Attribution 3.0 Unported
License](http://creativecommons.org/licenses/by/3.0/). This applies to all
documents and translations in this repository.
Based on a work at
[github.com/necolas/idiomatic-html](https://github.com/necolas/idiomatic-html).