Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Website improvements #2053

Merged
merged 4 commits into from
May 7, 2020
Merged

Website improvements #2053

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b99a72c
Website improvements
RunDevelopment Sep 10, 2019
b2b5713
Code blocks for longer commands
RunDevelopment Sep 16, 2019
ee0cd58
Merge branch 'master' into website-improvements
RunDevelopment May 6, 2020
484d9e5
Added some more links
RunDevelopment May 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ <h1>Full list of features</h1>
<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: IE9+, Firefox, Chrome, Safari, <a href="faq.html#this-page-doesnt-work-in-opera">Opera</a>, most Mobile browsers</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>
Expand All @@ -115,15 +115,15 @@ <h1>Full list of features</h1>
<h1>Limitations</h1>
<ul>
<li>Any pre-existing HTML in the code will be stripped off. <a href="faq.html#if-pre-existing-html-is-stripped-off-how-can-i-highlight">There are ways around it though</a>.</li>
<li>Regex-based so it *will* fail on certain edge cases, which are documented in the <a href="known-failures.html">known failues page</a>.</li>
<li>No IE 6-8 support. If someone can read code, they are probably in the 85% of the population with a modern browser.</li>
<li>Regex-based so it *will* fail on certain edge cases, which are documented in the <a href="known-failures.html">known failures page</a>.</li>
<li>No IE 6-10 support. If someone can read code, they are probably in the 95% of the population with a modern browser.</li>
</ul>
</section>

<section id="basic-usage" class="language-markup">
<h1>Basic usage</h1>

<p>You will need to include the <code>prism.css</code> and <code>prism.js</code> files you downloaded in your page. Example:
<p>You will need to include the <code>prism.css</code> and <code>prism.js</code> files you <a href="download.html">downloaded</a> in your page. Example:
<pre><code>&lt;!DOCTYPE html>
&lt;html>
&lt;head>
Expand Down Expand Up @@ -158,8 +158,8 @@ <h1>Basic usage</h1>
window.Prism.manual = true;
&lt;/script>
&lt;script src="prism.js">&lt;/script></code></pre>
<h2>Usage with CDNs</h2>

<h2 id="basic-usage-cdn">Usage with CDNs</h2>

<p>In combination with CDNs, we recommend using the <a href="plugins/autoloader">Autoloader plugin</a> which automatically loads languages when necessary.</p>

Expand All @@ -178,9 +178,9 @@ <h2>Usage with CDNs</h2>
<code>&lt;/body>
&lt;/html></code></pre>

<p>CDNs which provide PrismJS are e.g. <a href="https://cdnjs.com/libraries/prism">cdnjs</a> and <a href="https://www.jsdelivr.com/package/npm/prismjs">jsDelivr</a>.</p>
<p>CDNs which provide PrismJS are e.g. <a href="https://cdnjs.com/libraries/prism">cdnjs</a>, <a href="https://www.jsdelivr.com/package/npm/prismjs">jsDelivr</a>, and <a href="https://unpkg.com/browse/prismjs@1/">UNPKG</a>.</p>

<h2>Usage with Webpack, Browserify, & Other Bundlers</h2>
<h2 id="basic-usage-bundlers">Usage with Webpack, Browserify, & Other Bundlers</h2>

<p>If you want to use Prism with a bundler, install Prism with <code>npm</code>:</p>

Expand All @@ -195,7 +195,7 @@ <h2>Usage with Webpack, Browserify, & Other Bundlers</h2>
the minimum number of languages and plugins to satisfy your needs.
See that plugin's documentation for configuration details.</p>

<h2>Usage with Node</h2>
<h2 id="basic-usage-node">Usage with Node</h2>

<p>If you want to use Prism on the server or through the command line, Prism can be used with Node.js as well.
This might be useful if you're trying to generate static HTML pages with highlighted code for environments that don't support browser-side JS, like <a href="https://www.ampproject.org/">AMP pages</a>.</p>
Expand Down
18 changes: 18 additions & 0 deletions scripts/code.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,24 @@ if (toc.children.length > 0) {

})();

/**
* Linkify h2
*/
(function () {
$$('section h2[id]').forEach(function (h2) {
var text = h2.textContent;
h2.innerHTML = '';

$u.element.create('a', {
properties: {
href: window.location.pathname + '#' + h2.id
},
contents: text,
inside: h2
});
});
})();

// calc()
(function(){
if(!window.PrefixFree) return;
Expand Down
9 changes: 6 additions & 3 deletions style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,13 @@ section h1 {
font-style: normal;
}

section h1 > a {
section h1 > a,
section h2[id] > a {
text-decoration: none;
}

section h1 > a:before {
section h1 > a:before,
section h2[id] > a:before {
content: '§';
position: absolute;
padding: 0 .2em;
Expand All @@ -62,7 +64,8 @@ section h1 {
text-shadow: 0 1px white;
}

section h1 > a:hover:before {
section h1 > a:hover:before,
section h2[id] > a:hover:before {
color: black;
background: #f1ad26;
}
Expand Down
129 changes: 64 additions & 65 deletions test-suite.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
<div class="intro" data-src="templates/header-main.html" data-type="text/html"></div>

<h2>Running the test suite</h2>

<p>Prism has a test suite, that ensures that the correct tokens are matched.</p>
</header>

Expand All @@ -27,12 +28,11 @@ <h1>Running the test suite</h1>
<p>Running the test suite is simple: just call <code class="language-bash">npm test</code>.</p>
<p>All test files are run in isolation. A new prism instance is created for each test case. This will slow the test runner a bit down, but we can be sure that nothing leaks into the next test case.</p>

<section id="running-tests-for-specific-languages">
<h2>Running tests for specific languages</h2>

<p>To run the tests only for one language, you can use the <code>language</code> parameter: <code class="language-bash">npm run test:languages -- --language=markup</code>.</p>
<p>You can even specify multiple languages: <code class="language-bash">npm run test:languages -- --language=markup --language=css</code>.</p>
</section>
<h2 id="running-tests-for-specific-languages">Running tests for specific languages</h2>

<p>To run the tests only for one language, you can use the <code>language</code> parameter: <code class="language-bash">npm run test:languages -- --language=markup</code>.</p>
RunDevelopment marked this conversation as resolved.
Show resolved Hide resolved
<p>You can even specify multiple languages: <code class="language-bash">npm run test:languages -- --language=markup --language=css</code>.</p>
RunDevelopment marked this conversation as resolved.
Show resolved Hide resolved
</section>

<section id="writing-tests">
Expand All @@ -41,59 +41,59 @@ <h1>Writing tests</h1>
<p>Thank you for writing tests! Tests are awesome! They ensure, that we can improve the codebase without breaking anything. Also, this way, we can ensure that upgrading Prism is as painless as possible for you.</p>
<p>You can add new tests by creating a new test case file (with the <code>.test</code> file extension) in the tests directory which is located at <code>/tests/languages/${language}</code>.</p>

<section id="writing-tests-directories">
<h2>Language directories</h2>
<p>All tests are sorted into directories in the <code>tests/languages</code> directory. Each directory name encodes, which language you are currently testing.</p>
<p><strong>All language names must match the names from the definition in <code>components.js</code>.</strong></p>

<h3>Example 1: testing a language in isolation (default use case)</h3>
<p>Just put your test file into the directory of the language you want to test.</p>
<p>So, if you want to test CSS, put your test file in <code>/tests/languages/css</code> to test CSS only. If you create a test case in this directory, the test runner will ensure that the <code>css</code> language definition including all required language definitions are correctly loaded.</p>

<h3>Example 2: testing language injection</h3>
<p>If you want to test language injection, you typically need to load two or more languages where one language is the “main” language that is being tested, with all other languages being injected into it.</p>
<p>You need to define multiple languages by separating them using a <code>+</code> sign: <code>markup+php</code>.</p>
<p>The languages are loaded in order, so first markup (+ dependencies) is loaded, then php (+ dependencies). The test loader ensures that no language is loaded more than once (for example if two languages have the same dependencies).</p>
<p>By default the last language is the main language: <code>php+markup</code> will have <code>markup</code> as main language. This is equal to putting your code in the following code block:</p>
<pre><code class="language-markup">...

<h2 id="writing-tests-directories">Language directories</h2>

<p>All tests are sorted into directories in the <code>tests/languages</code> directory. Each directory name encodes, which language you are currently testing.</p>
<p><strong>All language names must match the names from the definition in <code>components.js</code>.</strong></p>

<h3>Example 1: testing a language in isolation (default use case)</h3>
<p>Just put your test file into the directory of the language you want to test.</p>
<p>So, if you want to test CSS, put your test file in <code>/tests/languages/css</code> to test CSS only. If you create a test case in this directory, the test runner will ensure that the <code>css</code> language definition including all required language definitions are correctly loaded.</p>

<h3>Example 2: testing language injection</h3>
<p>If you want to test language injection, you typically need to load two or more languages where one language is the “main” language that is being tested, with all other languages being injected into it.</p>
<p>You need to define multiple languages by separating them using a <code>+</code> sign: <code>markup+php</code>.</p>
<p>The languages are loaded in order, so first markup (+ dependencies) is loaded, then php (+ dependencies). The test loader ensures that no language is loaded more than once (for example if two languages have the same dependencies).</p>
<p>By default the last language is the main language: <code>php+markup</code> will have <code>markup</code> as main language. This is equal to putting your code in the following code block:</p>
<pre><code class="language-markup">...
&lt;pre>&lt;code class="language-markup">
&lt;!-- your code here -->
&lt;/code>&lt;pre>
...</code></pre>

<p>If you need to load the languages in a given order, but you don't want to use the last language as main language, you can mark the main language with an exclamation mark: <code>php!+markup</code>. This will use <code>php</code> as main language. (You can only define one main language. The test runner will fail all tests in directories with more than one main language.)</p>

<p><em>Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).</em></p>
</section>

<section id="writing-tests-creating-your-test-case-file">
<h2>Creating your test case file</h2>
<p>At first you need to create a new file in the language directory, you want to test.</p>
<p><strong>Use a proper name for your test case.</strong> Please use one case of the following conventions:</p>
<ul>
<li><code>issue{issueid}</code>: reference a github issue id (example: <code>issue588.test</code>).</li>
<li><code>{featurename}_feature</code>: group all tests to one feature in one file (example: <code>string_interpolation_feature.test</code>).</li>
<li><code>{language}_inclusion</code>: test inclusion of one language into the other (example: <code>markup!+css/css_inclusion.test</code> will test CSS inclusion into markup).</li>
</ul>
<p>You can use all conventions as a prefix, so <code>string_interpolation_feature_inline.test</code> is possible. <strong>But please take a minute or two to think of a proper name of your test case file. You are writing code not only for the computers, but also for your fellow developers.</strong></p>
</section>

<section id="writing-tests-writing-your-test">
<h2>Writing your test</h2>
<p>The structure of a test case file is as follows:</p>
<pre><code>
<p>If you need to load the languages in a given order, but you don't want to use the last language as main language, you can mark the main language with an exclamation mark: <code>php!+markup</code>. This will use <code>php</code> as main language. (You can only define one main language. The test runner will fail all tests in directories with more than one main language.)</p>

<p><em>Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).</em></p>


<h2 id="writing-tests-creating-your-test-case-file">Creating your test case file</h2>

<p>At first you need to create a new file in the language directory, you want to test.</p>
<p><strong>Use a proper name for your test case.</strong> Please use one case of the following conventions:</p>
<ul>
<li><code>issue{issueid}</code>: reference a github issue id (example: <code>issue588.test</code>).</li>
<li><code>{featurename}_feature</code>: group all tests to one feature in one file (example: <code>string_interpolation_feature.test</code>).</li>
<li><code>{language}_inclusion</code>: test inclusion of one language into the other (example: <code>markup!+css/css_inclusion.test</code> will test CSS inclusion into markup).</li>
</ul>
<p>You can use all conventions as a prefix, so <code>string_interpolation_feature_inline.test</code> is possible. <strong>But please take a minute or two to think of a proper name of your test case file. You are writing code not only for the computers, but also for your fellow developers.</strong></p>


<h2 id="writing-tests-writing-your-test">Writing your test</h2>
<p>The structure of a test case file is as follows:</p>
<pre><code>
... language snippet...
----
... the simplified token stream you expect ...</code></pre>

<p>Your file is built up of two or three sections, separated by ten or more dashes <code>-</code>, starting at the begin of the line:</p>
<ol>
<li>Your language snippet. The code you want to compile using Prism. (<strong>required</strong>)</li>
<li>The simplified token stream you expect. Needs to be valid JSON. (<strong>required</strong>)</li>
<li>A comment explaining the test case. (<em>optional</em>)</li>
</ol>
<p>The easiest way would be to look at an existing test file:</p>
<pre><code>var a = 5;
<p>Your file is built up of two or three sections, separated by ten or more dashes <code>-</code>, starting at the begin of the line:</p>
<ol>
<li>Your language snippet. The code you want to compile using Prism. (<strong>required</strong>)</li>
<li>The simplified token stream you expect. Needs to be valid JSON. (<strong>required</strong>)</li>
<li>A comment explaining the test case. (<em>optional</em>)</li>
</ol>
<p>The easiest way would be to look at an existing test file:</p>
<pre><code>var a = 5;

----------------------------------------------------

Expand All @@ -108,22 +108,21 @@ <h2>Writing your test</h2>
----------------------------------------------------

This is a comment explaining this test case.</code></pre>
</section>

<section>
<h2>Explaining the simplified token stream</h2>
<p>While compiling, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).</p>
<p>As these trees are hard to write by hand, the test runner uses a simplified version of it.</p>
<p>It uses the following rules:</p>
<ul>
<li><code>Token</code> objects are transformed into an array: <code>[token.type, token.content]</code> (whereas <code>token.content</code> can be a nested structure).</li>
<li>All strings that are either empty or only contain whitespace, are removed from the token stream.</li>
<li>All empty structures are removed.</li>
</ul>
<p>To get a pretty-printed version of the simplified token stream of a failed test, add the <code>--pretty</code> modifier. Keep in mind that the pretty-printed token stream is indented using spaces, you may need to convert these to tabs. (Most editors today have an option which handles the conversion for you.)<br>
E.g. <code class="language-bash">npm run test:languages -- --pretty</code>.</p>
<p>For further information: reading the tests of the test runner (<code>tests/testrunner-tests.js</code>) will help you understand the transformation.</p>
</section>


<h2 id="writing-tests-explaining-the-simplified-token-stream">Explaining the simplified token stream</h2>

<p>While compiling, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).</p>
<p>As these trees are hard to write by hand, the test runner uses a simplified version of it.</p>
<p>It uses the following rules:</p>
<ul>
<li><code>Token</code> objects are transformed into an array: <code>[token.type, token.content]</code> (whereas <code>token.content</code> can be a nested structure).</li>
<li>All strings that are either empty or only contain whitespace, are removed from the token stream.</li>
<li>All empty structures are removed.</li>
</ul>
<p>To get a pretty-printed version of the simplified token stream of a failed test, add the <code>--pretty</code> modifier. Keep in mind that the pretty-printed token stream is indented using spaces, you may need to convert these to tabs. (Most editors today have an option which handles the conversion for you.)<br>
E.g. <code class="language-bash">npm run test:languages -- --pretty</code>.</p>
<p>For further information: reading the tests of the test runner (<code>tests/testrunner-tests.js</code>) will help you understand the transformation.</p>
</section>

<section id="writing-specific-tests">
Expand Down