From 8e1f38ff44233dac3db82c2e663d56740563bbbc Mon Sep 17 00:00:00 2001 From: Michael Schmidt Date: Wed, 4 Nov 2020 11:44:43 +0100 Subject: [PATCH] Website: Updated and improved guide on "Extending Prism" page (#2586) --- extending.html | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/extending.html b/extending.html index 6005a6ed3c..35d7463ac6 100644 --- a/extending.html +++ b/extending.html @@ -129,7 +129,7 @@

Creating a new language definition

This will make your language available to the test page, or more precise: your local version of it. You can open your local test.html page in any browser, select your language, and see how your language definition highlights any code you input.

-

Note: You have to reload the test page to apply changes made to prism-foo-bar.js but you don't have to rebuild Prism itself. However, if you change components.json (e.g. because you added a dependency) then these changes will not show up until you rebuild Prism.

+

Note: You have to reload the test page to apply changes made to prism-foo-bar.js but you don't have to rebuild Prism itself. However, if you change components.json (e.g. because you added a dependency) then these changes will not show up on the test page until you rebuild Prism.

  • Write the language definition.

    @@ -172,7 +172,7 @@

    Creating a new language definition

    }
  • -

    Add some tests.

    +

    Adding tests.

    Create a folder tests/languages/foo-bar/. This is where your test files will live. The test format and how to run tests is described here.

    @@ -184,8 +184,6 @@

    Creating a new language definition

    ---------------------------------------------------- -[ "JSON of the simplified token stream. We will add this later." ] - ---------------------------------------------------- Brief description. @@ -197,30 +195,30 @@

    Creating a new language definition

    Add the code to test and a brief description.

  • -

    Verify that your language definition correctly highlights the test code. This can be done using the test page.
    +

    Verify that your language definition correctly highlights the test code. This can be done using your local version of the test page.
    Note: Using the Show tokens options, you see the token stream your language definition created.

  • Once you carefully checked that the test case is handled correctly (i.e. by using the test page), run the following command:

    - npm run test:languages -- --language=foo-bar --pretty -

    This command will check only your test files. The new test will fail because the specified JSON is incorrect but the error message of the failed test will also include the JSON of the simplified token stream Prism created. This is what we're after. Replace the current incorrect JSON with the output labeled Token Stream. (Please also adjust the indentation. We use tabs.)

    + npm run test:languages -- --language=foo-bar --accept +

    This command will take the token stream your language definition currently produces and inserted into the test file. The empty space between the two lines separating the code and the description of test case will be replaced with a simplified version of the token stream.

  • -

    Carefully check that the token stream JSON you just inserted is what you expect.

    +

    Carefully check that the inserted token stream JSON is what you expect.

    • -
  • Re-run npm run test:languages -- --language=foo-bar --pretty to verify that the test passes.
    • +
  • Re-run npm run test:languages -- --language=foo-bar to verify that the test passes.
    • -
  • -

    Run npm test to check that all tests pass, not just your language tests.
    - This will usually pass without problems. If you can't get all the tests to pass, skip this step.

    -

  • Add an example page.

    Create a new file examples/prism-foo-bar.html. This will be the template containing the example markup. Just look at other examples to see how these files are structured.
    We don't have any rules as to what counts as an example, so a single Full example section where you present the highlighting of the major features of the language is enough.

    • +
  • +

    Run npm test to check that all tests pass, not just your language tests.
    + This will usually pass without problems. If you can't get all the tests to pass, skip this step.

    +

  • Run npm run build again.