From ce0fa227a7d7bbded8a7d947a90e45ff3abf8a58 Mon Sep 17 00:00:00 2001 From: Michael Schmidt Date: Thu, 7 May 2020 13:40:37 +0200 Subject: [PATCH] Website improvements (#2053) --- extending.html | 8 +-- index.html | 16 +++--- scripts/code.js | 18 +++++++ style.css | 9 ++-- test-suite.html | 136 +++++++++++++++++++++++++----------------------- 5 files changed, 107 insertions(+), 80 deletions(-) diff --git a/extending.html b/extending.html index de25798507..be51b557f3 100644 --- a/extending.html +++ b/extending.html @@ -145,7 +145,7 @@

Creating a new language definition

In this example, we choose 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]*)*$/.

  • -

    Edit 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.)
    +

    Edit 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"
 }
    -

    If your language definition depends any other languages, you have to specify this here as well by adding a "require" property. E.g. "require": "clike", or "require" : ["markup", "css"]. For more information on dependencies read the declaring dependencies section.

    +

    If your language definition depends any other languages, you have to specify this here as well by adding a "require" property. E.g. "require": "clike", or "require" : ["markup", "css"]. For more information on dependencies read the declaring dependencies section.

    Note: Any changes made to components.json require a rebuild (see step 3).

    • @@ -266,7 +266,7 @@

    Dependencies

    Languages and plugins can depend on each other, so Prism has its own dependency system to declare and resolve dependencies.

    -

    Declaring dependencies

    +

    Declaring dependencies

    You declare a dependency by adding a property to the entry of your language or plugin in the 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.

    @@ -354,7 +354,7 @@

    Dependency kinds

    Note: You can declare a component as both require and modify

    -

    Resolving dependencies

    +

    Resolving dependencies

    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 loadLanguages function in NodeJS, the AutoLoader, or our Babel plugin.

    diff --git a/index.html b/index.html index e8048d6f8c..24f1f99dfb 100644 --- a/index.html +++ b/index.html @@ -100,7 +100,7 @@

    Full list of features

  • Very easy to extend without modifying the code, due to Prism’s plugin architecture. Multiple hooks are scattered throughout the source.
  • Very easy to define new languages. Only thing you need is a good understanding of regular expressions
  • All styling is done through CSS, with sensible class names rather than ugly namespaced abbreviated nonsense.
    • -
  • Wide browser support: IE11, Firefox, Chrome, Safari, Opera, most Mobile browsers
    • +
  • Wide browser support: Edge, IE11, Firefox, Chrome, Safari, Opera, most Mobile browsers
  • Highlights embedded languages (e.g. CSS inside HTML, JavaScript inside HTML)
  • Highlights inline code as well, not just code blocks
  • Highlights nested languages (CSS in HTML, JavaScript in HTML)
    • @@ -115,16 +115,16 @@

    Full list of features

    Limitations

    Basic usage

    -

    You will need to include the prism.css and prism.js files you downloaded in your page. Example: +

    You will need to include the 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

    In combination with CDNs, we recommend using the Autoloader plugin which automatically loads languages when necessary.

    @@ -179,9 +179,9 @@

    Usage with CDNs

    </body> </html> -

    CDNs which provide PrismJS are e.g. cdnjs and jsDelivr.

    +

    CDNs which provide PrismJS are e.g. cdnjs, jsDelivr, and UNPKG.

    -

    Usage with Webpack, Browserify, & Other Bundlers

    +

    Usage with Webpack, Browserify, & Other Bundlers

    If you want to use Prism with a bundler, install Prism with npm:

    @@ -196,7 +196,7 @@

    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.

    -

    Usage with Node

    +

    Usage with Node

    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 @@

    Running the test suite

    +

    Prism has a test suite, that ensures that the correct tokens are matched.

    @@ -27,12 +28,16 @@

    Running the test suite

    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.

    -
    -

    Running tests for specific languages

    -

    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.

    -
    +

    Running tests for specific languages

    + +

    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
    @@ -41,59 +46,59 @@

    Writing tests

    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}.

    -
    -

    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:

    - 
    ...
+
+	
    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).
    
-
    - -
    -

    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:

    - 
    
+	
    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:
    
-		
      
-			
    1. Your language snippet. The code you want to compile using Prism. (required)
      2. 
-			
    2. The simplified token stream you expect. Needs to be valid JSON. (required)
      3. 
-			
    3. A comment explaining the test case. (optional)
      4. 
-		
    
-		
    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:
    
+	
      
+		
    1. Your language snippet. The code you want to compile using Prism. (required)
      2. 
+		
    2. The simplified token stream you expect. Needs to be valid JSON. (required)
      3. 
+		
    3. A comment explaining the test case. (optional)
      4. 
+	
    
+	
    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.
    
-
    - -
    -

    Explaining the simplified token stream

    -

    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).
      • -
    • All strings that are either empty or only contain whitespace, are removed from the token stream.
      • -
    • All empty structures are removed.
      • -
    -

    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.

    -
    + + +

    Explaining the simplified token stream

    + +

    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).
      • +
    • All strings that are either empty or only contain whitespace, are removed from the token stream.
      • +
    • All empty structures are removed.
      • +
    +

    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.