From ce0fa227a7d7bbded8a7d947a90e45ff3abf8a58 Mon Sep 17 00:00:00 2001
From: Michael Schmidt In this example, we choose Edit Edit If your language definition depends any other languages, you have to specify this here as well by adding a If your language definition depends any other languages, you have to specify this here as well by adding a Note: Any changes made to Languages and plugins can depend on each other, so Prism has its own dependency system to declare and resolve dependencies. You declare a dependency by adding a property to the entry of your language or plugin in the Note: You can declare a component as both We consider the dependencies of components an implementation detail, so they may change from release to release. Prism will usually resolve dependencies for you automatically. So you won't have to worry about dependency loading if you download a bundle or use the You will need to include the You will need to include the In combination with CDNs, we recommend using the Autoloader plugin which automatically loads languages when necessary. CDNs which provide PrismJS are e.g. cdnjs and jsDelivr. CDNs which provide PrismJS are e.g. cdnjs, jsDelivr, and UNPKG. If you want to use Prism with a bundler, install Prism with Creating a new language definition
foo-bar
as the id of the new language. The language id has to be unique and should work well with the language-xxxx
CSS class name Prism uses to refer to language definitions. Your language id should ideally match the regular expression /^[a-z][a-z\d]*(?:-[a-z][a-z\d]*)*$/
.components.json
to register the new language by adding it to the languages
object. (Please note that all language entries are sorted alphabetically by title.)
+ components.json
to register the new language by adding it to the languages
object. (Please note that all language entries are sorted alphabetically by title.)
Our new entry for this example will look like this:
- "foo-bar": {
@@ -153,7 +153,7 @@
Creating a new language definition
"owner": "Your GitHub name"
}"require"
property. E.g. "require": "clike"
, or "require" : ["markup", "css"]
. For more information on dependencies read the declaring dependencies section."require"
property. E.g. "require": "clike"
, or "require" : ["markup", "css"]
. For more information on dependencies read the declaring dependencies section.components.json
require a rebuild (see step 3).Dependencies
Declaring dependencies
+ Declaring dependencies
components.json
file. The name of the property will be dependency kind and its value will be the component id of the dependee. If multiple languages or plugins are depended upon then you can also declare an array of component ids.Dependency kinds
require
and modify
Resolving dependencies
+ Resolving dependencies
loadLanguages
function in NodeJS, the AutoLoader, or our Babel plugin.Full list of features
Full list of features
Limitations
Basic usage
- prism.css
and prism.js
files you downloaded in your page. Example:
+ prism.css
and prism.js
files you downloaded in your page. Example:
- <!DOCTYPE html>
<html>
<head>
@@ -160,7 +160,7 @@
Basic usage
</script>
<script src="prism.js"></script>Usage with CDNs
+ Usage with CDNs
Usage with CDNs
</body>
</html>
- Usage with Webpack, Browserify, & Other Bundlers
+ Usage with Webpack, Browserify, & Other Bundlers
npm
:Usage with Webpack, Browserify, & Other Bundlers
the minimum number of languages and plugins to satisfy your needs.
See that plugin's documentation for configuration details.
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 AMP pages.
diff --git a/scripts/code.js b/scripts/code.js index e6aad049ae..d41f88bedf 100644 --- a/scripts/code.js +++ b/scripts/code.js @@ -100,6 +100,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; diff --git a/style.css b/style.css index 00be1070a3..e86e07409a 100644 --- a/style.css +++ b/style.css @@ -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; @@ -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; } diff --git a/test-suite.html b/test-suite.html index 11bf139d35..4d4105482f 100644 --- a/test-suite.html +++ b/test-suite.html @@ -18,6 +18,7 @@Prism has a test suite, that ensures that the correct tokens are matched.
@@ -27,12 +28,16 @@Running the test suite is simple: just call npm test
.
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.
-To run the tests only for one language, you can use the language
parameter: npm run test:languages -- --language=markup
.
You can even specify multiple languages: npm run test:languages -- --language=markup --language=css
.
To run the tests only for one language, you can use the language
parameter:
npm run test:languages -- --language=markup
+
+ You can even specify multiple languages:
+ +npm run test:languages -- --language=markup --language=css
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.
You can add new tests by creating a new test case file (with the .test
file extension) in the tests directory which is located at /tests/languages/${language}
.
All tests are sorted into directories in the tests/languages
directory. Each directory name encodes, which language you are currently testing.
All language names must match the names from the definition in components.js
.
Just put your test file into the directory of the language you want to test.
-So, if you want to test CSS, put your test file in /tests/languages/css
to test CSS only. If you create a test case in this directory, the test runner will ensure that the css
language definition including all required language definitions are correctly loaded.
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.
-You need to define multiple languages by separating them using a +
sign: markup+php
.
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).
-By default the last language is the main language: php+markup
will have markup
as main language. This is equal to putting your code in the following code block:
...
+
+ Language directories
+
+ All tests are sorted into directories in the tests/languages
directory. Each directory name encodes, which language you are currently testing.
+ All language names must match the names from the definition in components.js
.
+
+ Example 1: testing a language in isolation (default use case)
+ Just put your test file into the directory of the language you want to test.
+ So, if you want to test CSS, put your test file in /tests/languages/css
to test CSS only. If you create a test case in this directory, the test runner will ensure that the css
language definition including all required language definitions are correctly loaded.
+
+ Example 2: testing language injection
+ 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.
+ You need to define multiple languages by separating them using a +
sign: markup+php
.
+ 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).
+ By default the last language is the main language: php+markup
will have markup
as main language. This is equal to putting your code in the following code block:
+ ...
<pre><code class="language-markup">
<!-- your code here -->
</code><pre>
...
- 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: php!+markup
. This will use php
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.)
-
- Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).
-
At first you need to create a new file in the language directory, you want to test.
-Use a proper name for your test case. Please use one case of the following conventions:
-issue{issueid}
: reference a github issue id (example: issue588.test
).{featurename}_feature
: group all tests to one feature in one file (example: string_interpolation_feature.test
).{language}_inclusion
: test inclusion of one language into the other (example: markup!+css/css_inclusion.test
will test CSS inclusion into markup).You can use all conventions as a prefix, so string_interpolation_feature_inline.test
is possible. 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.
The structure of a test case file is as follows:
-
+ 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: php!+markup
. This will use php
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.)
+
+ Note: by loading multiple languages you can do integration tests (ensure that loading two or more languages together won't break anything).
+
+
+ Creating your test case file
+
+ At first you need to create a new file in the language directory, you want to test.
+ Use a proper name for your test case. Please use one case of the following conventions:
+
+ issue{issueid}
: reference a github issue id (example: issue588.test
).
+ {featurename}_feature
: group all tests to one feature in one file (example: string_interpolation_feature.test
).
+ {language}_inclusion
: test inclusion of one language into the other (example: markup!+css/css_inclusion.test
will test CSS inclusion into markup).
+
+ You can use all conventions as a prefix, so string_interpolation_feature_inline.test
is possible. 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.
+
+
+ Writing your test
+ The structure of a test case file is as follows:
+
... language snippet...
----
... the simplified token stream you expect ...
- Your file is built up of two or three sections, separated by ten or more dashes -
, starting at the begin of the line:
-
- - Your language snippet. The code you want to compile using Prism. (required)
- - The simplified token stream you expect. Needs to be valid JSON. (required)
- - A comment explaining the test case. (optional)
-
- The easiest way would be to look at an existing test file:
- var a = 5;
+ Your file is built up of two or three sections, separated by ten or more dashes -
, starting at the begin of the line:
+
+ - Your language snippet. The code you want to compile using Prism. (required)
+ - The simplified token stream you expect. Needs to be valid JSON. (required)
+ - A comment explaining the test case. (optional)
+
+ The easiest way would be to look at an existing test file:
+ var a = 5;
----------------------------------------------------
@@ -108,22 +113,23 @@ Writing your test
----------------------------------------------------
This is a comment explaining this test case.
-
While compiling, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).
-As these trees are hard to write by hand, the test runner uses a simplified version of it.
-It uses the following rules:
-Token
objects are transformed into an array: [token.type, token.content]
(whereas token.content
can be a nested structure).To get a pretty-printed version of the simplified token stream of a failed test, add the --pretty
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.)
- E.g. npm run test:languages -- --pretty
.
For further information: reading the tests of the test runner (tests/testrunner-tests.js
) will help you understand the transformation.
While compiling, Prism transforms your source code into a token stream. This is basically a tree of nested tokens (or arrays, or strings).
+As these trees are hard to write by hand, the test runner uses a simplified version of it.
+It uses the following rules:
+Token
objects are transformed into an array: [token.type, token.content]
(whereas token.content
can be a nested structure).To get a pretty-printed version of the simplified token stream of a failed test, add the --pretty
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.)
npm run test:languages -- --pretty
+
+ For further information: reading the tests of the test runner (tests/testrunner-tests.js
) will help you understand the transformation.