Website: Added and updated documentation (#2654)

I updated a few of the entries in the "Full list of features" section (consistent formatting, a bit of grammar, nothing big). For some reason, we had both

- "Highlights embedded languages (e.g. CSS inside HTML, JavaScript inside HTML)" and 
- "Highlights nested languages (CSS in HTML, JavaScript in HTML)"

in there. They are sort of the same, so I removed one.

I also added a note regarding escaping and gave the manual highlighting section its own heading.

assets/style.css

@@ -75,11 +75,13 @@ p {
 }
 
 section h1,
-h2 {
+h2,
+h3 {
 	margin: 1em 0 .3em;
 }
 
-h2 {
+h2,
+h3 {
 	font-weight: normal;
 }
 
@@ -141,10 +143,6 @@ footer:before {
 	background-repeat: repeat-x;
 	background-image: linear-gradient(45deg, transparent 34%, white 34%, white 66%, transparent 66%),
 	                  linear-gradient(135deg, transparent 34%, white 34%, white 66%, transparent 66%);
-}
-
-header {
-
 }
 
 	header .intro,

index.html

@@ -95,19 +95,23 @@ <h1>Full list of features</h1>
 			Prism forces you to use the correct element for marking up code: <code>&lt;code></code>.
 			On its own for inline code, or inside a <code>&lt;pre></code> for blocks of code.
 			In addition, the language is defined through the way recommended in the HTML5 draft: through a <code>language-xxxx</code> class.</li>
-		<li>The language definition is inherited. This means that if multiple code snippets have the same language, you can just define it once, in one of their common ancestors.</li>
-		<li>Supports <strong>parallelism with Web Workers</strong>, if available. Disabled by default (<a href="faq.html#why-is-asynchronous-highlighting-disabled-by-default">why?</a>).</li>
-		<li>Very easy to extend without modifying the code, due to Prism’s <a href="#plugins">plugin architecture</a>. Multiple hooks are scattered throughout the source.</li>
-		<li>Very easy to <a href="extending.html#language-definitions">define new languages</a>. Only thing you need is a good understanding of regular expressions</li>
-		<li>All styling is done through CSS, with <a href="faq.html#how-do-i-know-which-tokens-i-can-style-for">sensible class names</a> rather than ugly namespaced abbreviated nonsense.</li>
-		<li>Wide browser support: Edge, IE11, Firefox, Chrome, Safari, <a href="faq.html#this-page-doesnt-work-in-opera">Opera</a>, most Mobile browsers</li>
-		<li>Highlights embedded languages (e.g. CSS inside HTML, JavaScript inside HTML)</li>
-		<li>Highlights inline code as well, not just code blocks</li>
-		<li>Highlights nested languages (CSS in HTML, JavaScript in HTML)</li>
-		<li>It doesn’t force you to use any Prism-specific markup, not even a Prism-specific class name, only standard markup you should be using anyway. So, you can just try it for a while, remove it if you don’t like it and leave no traces behind.</li>
-		<li>Highlight specific lines and/or line ranges (requires <a href="plugins/line-highlight/">plugin</a>)</li>
-		<li>Show invisible characters like tabs, line breaks etc (requires <a href="plugins/show-invisibles/">plugin</a>)</li>
-		<li>Autolink URLs and emails, use Markdown links in comments (requires <a href="plugins/autolinker/">plugin</a>)</li>
+		<li>The <code>language-xxxx</code> class is inherited.
+			This means that if multiple code snippets have the same language, you can just define it once,in one of their common ancestors.</li>
+		<li>Supports <strong>parallelism with Web Workers</strong>, if available.
+			Disabled by default (<a href="faq.html#why-is-asynchronous-highlighting-disabled-by-default">why?</a>).</li>
+		<li>Very easy to extend without modifying the code, due to Prism’s <a href="#plugins">plugin architecture</a>.
+			Multiple hooks are scattered throughout the source.</li>
+		<li>Very easy to <a href="extending.html#language-definitions">define new languages</a>.
+			The only thing you need is a good understanding of regular expressions.</li>
+		<li>All styling is done through CSS, with <a href="faq.html#how-do-i-know-which-tokens-i-can-style-for">sensible class names</a> rather than ugly, namespaced, abbreviated nonsense.</li>
+		<li>Wide browser support: Edge, IE11, Firefox, Chrome, Safari, <a href="faq.html#this-page-doesnt-work-in-opera">Opera</a>, most mobile browsers.</li>
+		<li>Highlights embedded languages (e.g. CSS inside HTML, JavaScript inside HTML).</li>
+		<li>Highlights inline code as well, not just code blocks.</li>
+		<li>It doesn’t force you to use any Prism-specific markup, not even a Prism-specific class name, only standard markup you should be using anyway.
+			So, you can just try it for a while, remove it if you don’t like it and leave no traces behind.</li>
+		<li>Highlight specific lines and/or line ranges (requires <a href="plugins/line-highlight/">plugin</a>).</li>
+		<li>Show invisible characters like tabs, line breaks etc (requires <a href="plugins/show-invisibles/">plugin</a>).</li>
+		<li>Autolink URLs and emails, use Markdown links in comments (requires <a href="plugins/autolinker/">plugin</a>).</li>
 	</ul>
 </section>
 
@@ -147,13 +151,22 @@ <h1>Basic usage</h1>
 
 	<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>
+
 	<pre><code>&lt;pre>&lt;code class="language-css">p { color: red }&lt;/code>&lt;/pre></code></pre>
+
 	<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>If you want to prevent any elements from being automatically highlighted and instead use the <a href="extending.html#api">API</a>, you can set <code class="language-javascript">Prism.manual</code> to <code class="language-javascript">true</code> before the <code>DOMContentLoaded</code> event is fired. By setting the <code>data-manual</code> attribute on the <code>&lt;script></code> element containing Prism core, this will be done automatically.
+	<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>
+
+	<h3>Manual highlighting</h3>
+
+	<p>If you want to prevent any elements from being automatically highlighted and instead use the <a href="extending.html#api">API</a>, you can set <a href="docs/Prism.html#.manual"><code class="language-javascript">Prism.manual</code></a> to <code class="language-javascript">true</code> before the <code>DOMContentLoaded</code> event is fired. By setting the <code>data-manual</code> attribute on the <code>&lt;script></code> element containing Prism core, this will be done automatically.
 	Example:</p>
+
 	<pre><code>&lt;script src="prism.js" data-manual>&lt;/script></code></pre>
+
 	<p>or</p>
+
 	<pre><code>&lt;script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;