Skip to content

Commit

Permalink
Website: Improved basic usage section (#2777)
Browse files Browse the repository at this point in the history
  • Loading branch information
RunDevelopment authored Mar 5, 2021
1 parent bf4e7ba commit a120993
Showing 1 changed file with 12 additions and 5 deletions.
17 changes: 12 additions & 5 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -144,10 +144,6 @@ <h1>Basic usage</h1>
<p>Prism does its best to encourage good authoring practices. Therefore, it only works with <code>&lt;code></code> elements, since marking up code without a <code>&lt;code></code> element is semantically invalid.
<a href="https://www.w3.org/TR/html52/textlevel-semantics.html#the-code-element">According to the HTML5 spec</a>, the recommended way to define a code language is a <code>language-xxxx</code> class, which is what Prism uses.
Alternatively, Prism also supports a shorter version: <code>lang-xxxx</code>.</p>
<p>To make things easier however, Prism assumes that this language definition is inherited. Therefore, if multiple <code>&lt;code></code> elements have the same language, you can add the <code>language-xxxx</code> class on one of their common ancestors.
This way, you can also define a document-wide default language, by adding a <code>language-xxxx</code> class on the <code>&lt;body></code> or <code>&lt;html></code> element.</p>

<p>If you want to opt-out of highlighting for a <code>&lt;code></code> element that is a descendant of an element with a declared code language, you can add the class <code>language-none</code> to it (or any non-existing language, really).</p>

<p>The <a href="https://www.w3.org/TR/html5/grouping-content.html#the-pre-element">recommended way to mark up a code block</a>
(both for semantics and for Prism) is a <code>&lt;pre></code> element with a <code>&lt;code></code> element inside, like so:</p>
Expand All @@ -156,7 +152,18 @@ <h1>Basic usage</h1>

<p>If you use that pattern, the <code>&lt;pre></code> will automatically get the <code>language-xxxx</code> class (if it doesn’t already have it) and will be styled as a code block.</p>

<p><strong>Note</strong>: You have to escape all <code>&lt;</code> and <code>&amp;</code> characters inside <code>&lt;code></code> elements with <code>&amp;lt;</code> and <code>&amp;amp;</code> respectively, or else the browser might interpret them as an HTML tag or <a href="https://developer.mozilla.org/en-US/docs/Glossary/Entity">entity</a>. If you have large portions of HTML code, you can use the <a href="plugins/unescaped-markup/">Unescaped Markup plugin</a> to work around this.</p>
<p>Inline code snippets are done like this:</p>

<pre><code>&lt;code class="language-css">p { color: red }&lt;/code></code></pre>

<p><strong>Note</strong>: You have to escape all <code>&lt;</code> and <code>&amp;</code> characters inside <code>&lt;code></code> elements (code blocks and inline snippets) with <code>&amp;lt;</code> and <code>&amp;amp;</code> respectively, or else the browser might interpret them as an HTML tag or <a href="https://developer.mozilla.org/en-US/docs/Glossary/Entity">entity</a>. If you have large portions of HTML code, you can use the <a href="plugins/unescaped-markup/">Unescaped Markup plugin</a> to work around this.</p>

<h3>Language inheritance</h3>

<p>To make things easier however, Prism assumes that the language class is inherited. Therefore, if multiple <code>&lt;code></code> elements have the same language, you can add the <code>language-xxxx</code> class on one of their common ancestors.
This way, you can also define a document-wide default language, by adding a <code>language-xxxx</code> class on the <code>&lt;body></code> or <code>&lt;html></code> element.</p>

<p>If you want to opt-out of highlighting a <code>&lt;code></code> element that inherits its language, you can add the <code>language-none</code> class to it. The <code>none</code> language can also be inherited to disable highlighting for the element with the class and all of its descendants.</p>

<h3>Manual highlighting</h3>

Expand Down

0 comments on commit a120993

Please sign in to comment.