Skip to content

Commit

Permalink
Replace HTML entities in the HTML/CSS Style Guide
Browse files Browse the repository at this point in the history
The internal script that converts our style guides from Markdown to HTML now does this.
  • Loading branch information
tonyruscoe authored Jan 12, 2022
1 parent 106edd4 commit 18ed71c
Showing 1 changed file with 24 additions and 24 deletions.
48 changes: 24 additions & 24 deletions htmlcssguide.html
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ <h4 id="Indentation">2.2.1 Indentation</h4>

<p>Indent by 2 spaces at a time.</p>

<p>Don&#8217;t use tabs or mix tabs and spaces for indentation.</p>
<p>Dont use tabs or mix tabs and spaces for indentation.</p>

<pre><code class="language-html good">&lt;ul&gt;
&lt;li&gt;Fantastic
Expand Down Expand Up @@ -135,7 +135,7 @@ <h4 id="Comments">2.3.2 Comments</h4>

<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&#8217;s complexity.)</p>
depends on the projects complexity.)</p>

<h4 id="Action_Items">2.3.3 Action Items</h4>

Expand Down Expand Up @@ -170,7 +170,7 @@ <h4 id="Document_Type">3.1.1 Document Type</h4>

<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code>&lt;!DOCTYPE html&gt;</code>.</p>

<p>(It&#8217;s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
<p>(Its 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>

Expand Down Expand Up @@ -210,7 +210,7 @@ <h4 id="Semantics">3.1.3 Semantics</h4>

<p>Use HTML according to its purpose.</p>

<p>Use elements (sometimes incorrectly called &#8220;tags&#8221;) 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>

Expand Down Expand Up @@ -275,9 +275,9 @@ <h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4>
&lt;link rel="stylesheet" href="grid.css" media="screen"&gt;
&lt;link rel="stylesheet" href="print.css" media="print"&gt;
&lt;h1 style="font-size: 1em;"&gt;HTML sucks&lt;/h1&gt;
&lt;p&gt;I&#8217;ve read about this on a few sites but now I&#8217;m sure:
&lt;p&gt;Ive read about this on a few sites but now Im sure:
&lt;u&gt;HTML is stupid!!1&lt;/u&gt;
&lt;center&gt;I can&#8217;t believe there&#8217;s no way to control the styling of
&lt;center&gt;I cant believe theres no way to control the styling of
my website without doing everything all over again!&lt;/center&gt;
</code></pre>

Expand All @@ -286,10 +286,10 @@ <h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4>
&lt;title&gt;My first CSS-only redesign&lt;/title&gt;
&lt;link rel="stylesheet" href="default.css"&gt;
&lt;h1&gt;My first CSS-only redesign&lt;/h1&gt;
&lt;p&gt;I&#8217;ve read about this on a few sites but today I&#8217;m actually
&lt;p&gt;Ive read about this on a few sites but today Im actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
&lt;p&gt;It&#8217;s awesome!
&lt;p&gt;Its awesome!
</code></pre>

<h4 id="Entity_References">3.1.6 Entity References</h4>
Expand All @@ -301,14 +301,14 @@ <h4 id="Entity_References">3.1.6 Entity References</h4>
as well as among teams.</p>

<p>The only exceptions apply to characters with special meaning in HTML (like <code>&lt;</code>
and <code>&amp;</code>) as well as control or &#8220;invisible&#8221; characters (like no-break spaces).</p>
and <code>&amp;</code>) as well as control or invisible characters (like no-break spaces).</p>

<pre><code class="language-html bad">&lt;!-- Not recommended --&gt;
The currency symbol for the Euro is &amp;ldquo;&amp;eur;&amp;rdquo;.
</code></pre>

<pre><code class="language-html good">&lt;!-- Recommended --&gt;
The currency symbol for the Euro is &#8220;&#8364;&#8221;.
The currency symbol for the Euro is “€”.
</code></pre>

<h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
Expand All @@ -320,8 +320,8 @@ <h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
defines what tags can be omitted.</p>

<p>(This approach may require a grace period to be established as a wider guideline
as it&#8217;s significantly different from what web developers are typically taught.
For consistency and simplicity reasons it&#8217;s best served omitting all optional
as its significantly different from what web developers are typically taught.
For consistency and simplicity reasons its best served omitting all optional
tags, not just a selection.)</p>

<pre><code class="language-html bad">&lt;!-- Not recommended --&gt;
Expand Down Expand Up @@ -385,7 +385,7 @@ <h4 id="General_Formatting">3.2.1 General Formatting</h4>

<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&#8217;s acceptable to
<p>(If you run into issues around whitespace between list items its acceptable to
put all <code>li</code> elements in one line. A linter is encouraged to throw a warning
instead of an error.)</p>

Expand Down Expand Up @@ -490,7 +490,7 @@ <h4 id="ID_and_Class_Naming">4.1.2 ID and Class Naming</h4>
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 &#8220;helpers.&#8221;</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>
Expand Down Expand Up @@ -580,7 +580,7 @@ <h4 id="Shorthand_Properties">4.1.5 Shorthand Properties</h4>

<h4 id="0_and_Units">4.1.6 0 and Units</h4>

<p>Omit unit specification after &#8220;0&#8221; 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>

Expand All @@ -592,7 +592,7 @@ <h4 id="0_and_Units">4.1.6 0 and Units</h4>

<h4 id="Leading_0s">4.1.7 Leading 0s</h4>

<p>Omit leading &#8220;0&#8221;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>

Expand Down Expand Up @@ -637,7 +637,7 @@ <h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4>
(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 &#8220;demo&#8221; and &#8220;image&#8221; */
<pre><code class="language-css bad">/* Not recommended: does not separate the words demo and image */
.demoimage {}

/* Not recommended: uses underscore instead of hyphen */
Expand All @@ -651,16 +651,16 @@ <h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4>

<h4 id="Hacks">4.1.11 Hacks</h4>

<p>Avoid user agent detection as well as CSS &#8220;hacks&#8221;&#8212;try a different approach
<p>Avoid user agent detection as well as CSS hacks”—try a different approach
first.</p>

<p>It&#8217;s tempting to address styling differences over user agent detection or
<p>Its 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&#8212;and more frequently is too
means using detection and hacks more frequentlyand more frequently is too
frequently.</p>

<h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3>
Expand Down Expand Up @@ -727,7 +727,7 @@ <h4 id="Declaration_Stops">4.2.3 Declaration Stops</h4>

<h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4>

<p>Use a space after a property name&#8217;s colon.</p>
<p>Use a space after a property names colon.</p>

<p>Always use a single space between property and value (but no space between
property and colon) for consistency reasons.</p>
Expand Down Expand Up @@ -817,7 +817,7 @@ <h4 id="CSS_Quotation_Marks">4.2.8 CSS Quotation Marks</h4>
<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&#8212;<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");
Expand Down Expand Up @@ -861,13 +861,13 @@ <h2 id="Parting_Words">Parting Words</h2>

<p><em>Be consistent.</em></p>

<p>If you&#8217;re editing code, take a few minutes to look at the code around you and
<p>If youre 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&#8217;re saying rather than on how you&#8217;re saying
people can concentrate on what youre saying rather than on how youre 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
Expand Down

0 comments on commit 18ed71c

Please sign in to comment.