mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
Replace HTML entities in the HTML/CSS Style Guide
The internal script that converts our style guides from Markdown to HTML now does this.
This commit is contained in:
Tony Ruscoe
GitHub
parent
106edd4b39
commit
18ed71c507
|
|
@ -59,7 +59,7 @@ over HTTPS.</p>
|
|||
|
||||
<p>Indent by 2 spaces at a time.</p>
|
||||
|
||||
<p>Don’t use tabs or mix tabs and spaces for indentation.</p>
|
||||
<p>Don’t use tabs or mix tabs and spaces for indentation.</p>
|
||||
|
||||
<pre><code class="language-html good"><ul>
|
||||
<li>Fantastic
|
||||
|
|
@ -135,7 +135,7 @@ why is respective solution used or preferred?</p>
|
|||
|
||||
<p>(This item is optional as it is not deemed a realistic expectation to always
|
||||
demand fully documented code. Mileage may vary heavily for HTML and CSS code and
|
||||
depends on the project’s complexity.)</p>
|
||||
depends on the project’s complexity.)</p>
|
||||
|
||||
<h4 id="Action_Items">2.3.3 Action Items</h4>
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ depends on the project’s complexity.)</p>
|
|||
|
||||
<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code><!DOCTYPE html></code>.</p>
|
||||
|
||||
<p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
|
||||
<p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
|
||||
<a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser
|
||||
and infrastructure support and offers less room for optimization than HTML.)</p>
|
||||
|
||||
|
|
@ -210,7 +210,7 @@ HTML usage.</p>
|
|||
|
||||
<p>Use HTML according to its purpose.</p>
|
||||
|
||||
<p>Use elements (sometimes incorrectly called “tags”) for what they have been
|
||||
<p>Use elements (sometimes incorrectly called “tags”) for what they have been
|
||||
created for. For example, use heading elements for headings, <code>p</code> elements for
|
||||
paragraphs, <code>a</code> elements for anchors, etc.</p>
|
||||
|
||||
|
|
@ -275,9 +275,9 @@ templates than it is to update style sheets and scripts.</p>
|
|||
<link rel="stylesheet" href="grid.css" media="screen">
|
||||
<link rel="stylesheet" href="print.css" media="print">
|
||||
<h1 style="font-size: 1em;">HTML sucks</h1>
|
||||
<p>I’ve read about this on a few sites but now I’m sure:
|
||||
<p>I’ve read about this on a few sites but now I’m sure:
|
||||
<u>HTML is stupid!!1</u>
|
||||
<center>I can’t believe there’s no way to control the styling of
|
||||
<center>I can’t believe there’s no way to control the styling of
|
||||
my website without doing everything all over again!</center>
|
||||
</code></pre>
|
||||
|
||||
|
|
@ -286,10 +286,10 @@ templates than it is to update style sheets and scripts.</p>
|
|||
<title>My first CSS-only redesign</title>
|
||||
<link rel="stylesheet" href="default.css">
|
||||
<h1>My first CSS-only redesign</h1>
|
||||
<p>I’ve read about this on a few sites but today I’m actually
|
||||
<p>I’ve read about this on a few sites but today I’m actually
|
||||
doing it: separating concerns and avoiding anything in the HTML of
|
||||
my website that is presentational.
|
||||
<p>It’s awesome!
|
||||
<p>It’s awesome!
|
||||
</code></pre>
|
||||
|
||||
<h4 id="Entity_References">3.1.6 Entity References</h4>
|
||||
|
|
@ -301,14 +301,14 @@ templates than it is to update style sheets and scripts.</p>
|
|||
as well as among teams.</p>
|
||||
|
||||
<p>The only exceptions apply to characters with special meaning in HTML (like <code><</code>
|
||||
and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p>
|
||||
and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p>
|
||||
|
||||
<pre><code class="language-html bad"><!-- Not recommended -->
|
||||
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
|
||||
</code></pre>
|
||||
|
||||
<pre><code class="language-html good"><!-- Recommended -->
|
||||
The currency symbol for the Euro is “€”.
|
||||
The currency symbol for the Euro is “€”.
|
||||
</code></pre>
|
||||
|
||||
<h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
|
||||
|
|
@ -320,8 +320,8 @@ tags. The <a href="https://html.spec.whatwg.org/multipage/syntax.html#syntax-tag
|
|||
defines what tags can be omitted.</p>
|
||||
|
||||
<p>(This approach may require a grace period to be established as a wider guideline
|
||||
as it’s significantly different from what web developers are typically taught.
|
||||
For consistency and simplicity reasons it’s best served omitting all optional
|
||||
as it’s significantly different from what web developers are typically taught.
|
||||
For consistency and simplicity reasons it’s best served omitting all optional
|
||||
tags, not just a selection.)</p>
|
||||
|
||||
<pre><code class="language-html bad"><!-- Not recommended -->
|
||||
|
|
@ -385,7 +385,7 @@ on a new line.</p>
|
|||
|
||||
<p>Also, indent them if they are child elements of a block, list, or table element.</p>
|
||||
|
||||
<p>(If you run into issues around whitespace between list items it’s acceptable to
|
||||
<p>(If you run into issues around whitespace between list items it’s acceptable to
|
||||
put all <code>li</code> elements in one line. A linter is encouraged to throw a warning
|
||||
instead of an error.)</p>
|
||||
|
||||
|
|
@ -490,7 +490,7 @@ reflect the purpose of the element in question, or that are otherwise generic.</
|
|||
preferred as these are most understandable and the least likely to change.</p>
|
||||
|
||||
<p>Generic names are simply a fallback for elements that have no particular or no
|
||||
meaning different from their siblings. They are typically needed as “helpers.”</p>
|
||||
meaning different from their siblings. They are typically needed as “helpers.”</p>
|
||||
|
||||
<p>Using functional or generic names reduces the probability of unnecessary
|
||||
document or template changes.</p>
|
||||
|
|
@ -580,7 +580,7 @@ padding: 0 1em 2em;
|
|||
|
||||
<h4 id="0_and_Units">4.1.6 0 and Units</h4>
|
||||
|
||||
<p>Omit unit specification after “0” values, unless required.</p>
|
||||
<p>Omit unit specification after “0” values, unless required.</p>
|
||||
|
||||
<p>Do not use units after <code>0</code> values unless they are required.</p>
|
||||
|
||||
|
|
@ -592,7 +592,7 @@ padding: 0;
|
|||
|
||||
<h4 id="Leading_0s">4.1.7 Leading 0s</h4>
|
||||
|
||||
<p>Omit leading “0”s in values.</p>
|
||||
<p>Omit leading “0”s in values.</p>
|
||||
|
||||
<p>Do not put <code>0</code>s in front of values or lengths between -1 and 1.</p>
|
||||
|
||||
|
|
@ -637,7 +637,7 @@ easier, for example in search and replace operations.</p>
|
|||
(including none at all) other than hyphens, in order to improve understanding
|
||||
and scannability.</p>
|
||||
|
||||
<pre><code class="language-css bad">/* Not recommended: does not separate the words “demo” and “image” */
|
||||
<pre><code class="language-css bad">/* Not recommended: does not separate the words “demo” and “image” */
|
||||
.demoimage {}
|
||||
|
||||
/* Not recommended: uses underscore instead of hyphen */
|
||||
|
|
@ -651,16 +651,16 @@ and scannability.</p>
|
|||
|
||||
<h4 id="Hacks">4.1.11 Hacks</h4>
|
||||
|
||||
<p>Avoid user agent detection as well as CSS “hacks”—try a different approach
|
||||
<p>Avoid user agent detection as well as CSS “hacks”—try a different approach
|
||||
first.</p>
|
||||
|
||||
<p>It’s tempting to address styling differences over user agent detection or
|
||||
<p>It’s tempting to address styling differences over user agent detection or
|
||||
special CSS filters, workarounds, and hacks. Both approaches should be
|
||||
considered last resort in order to achieve and maintain an efficient and
|
||||
manageable code base. Put another way, giving detection and hacks a free pass
|
||||
will hurt projects in the long run as projects tend to take the way of least
|
||||
resistance. That is, allowing and making it easy to use detection and hacks
|
||||
means using detection and hacks more frequently—and more frequently is too
|
||||
means using detection and hacks more frequently—and more frequently is too
|
||||
frequently.</p>
|
||||
|
||||
<h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3>
|
||||
|
|
@ -727,7 +727,7 @@ reasons.</p>
|
|||
|
||||
<h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4>
|
||||
|
||||
<p>Use a space after a property name’s colon.</p>
|
||||
<p>Use a space after a property name’s colon.</p>
|
||||
|
||||
<p>Always use a single space between property and value (but no space between
|
||||
property and colon) for consistency reasons.</p>
|
||||
|
|
@ -817,7 +817,7 @@ selectors and property values.</p>
|
|||
<p>Do not use quotation marks in URI values (<code>url()</code>).</p>
|
||||
|
||||
<p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation
|
||||
marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p>
|
||||
marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p>
|
||||
|
||||
<pre><code class="language-css bad">/* Not recommended */
|
||||
@import url("https://www.google.com/css/maia.css");
|
||||
|
|
@ -861,13 +861,13 @@ sections with new lines.</p>
|
|||
|
||||
<p><em>Be consistent.</em></p>
|
||||
|
||||
<p>If you’re editing code, take a few minutes to look at the code around you and
|
||||
<p>If you’re editing code, take a few minutes to look at the code around you and
|
||||
determine its style. If they use spaces around all their arithmetic operators,
|
||||
you should too. If their comments have little boxes of hash marks around them,
|
||||
make your comments have little boxes of hash marks around them too.</p>
|
||||
|
||||
<p>The point of having style guidelines is to have a common vocabulary of coding so
|
||||
people can concentrate on what you’re saying rather than on how you’re saying
|
||||
people can concentrate on what you’re saying rather than on how you’re saying
|
||||
it. We present global style rules here so people know the vocabulary, but local
|
||||
style is also important. If code you add to a file looks drastically different
|
||||
from the existing code around it, it throws readers out of their rhythm when
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user