Extending page: Fixed typo + new alias section (#1949)
This commit is contained in:
Michael Schmidt
James DiGioia
parent
b65438539d
commit
24c8e71754
|
|
@ -133,16 +133,22 @@ ol.indent {
|
|||
<section id="creating-a-new-language-definition" class="language-none">
|
||||
<h1>Creating a new language definition</h1>
|
||||
|
||||
<p>This section will explain the usual workflow of creating a new language definition.</p>
|
||||
|
||||
<p>As an example, we will create the language definition of the fictional <em>Foo's Binary, Artistic Robots™</em> language or just Foo Bar for short.</p>
|
||||
|
||||
<ol class="indent">
|
||||
<li>
|
||||
<p>Create a new file <code>components/prism-lang-id.js</code>.</p>
|
||||
<p>Create a new file <code>components/prism-foo-bar.js</code>.</p>
|
||||
|
||||
<p>In this example, we choose <code>foo-bar</code> as the id of the new language. The language id has to be unique and should work well with the <code>language-xxxx</code> CSS class name Prism uses to refer to language definitions. Your language id should ideally match the regular expression <code>/^[a-z][a-z\d]*(?:-[a-z][a-z\d]*)*$/</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Edit <code>components.json</code> to register the new language by adding it to the <code>languages</code> object. (Please note that all language entries are sorted alphabetically by title.) <br>
|
||||
Your new entry will look like this:</p>
|
||||
Our new entry for this example will look like this:</p>
|
||||
|
||||
<pre><code class="language-js">"lang-id": {
|
||||
"title": "Language Title",
|
||||
<pre><code class="language-js">"foo-bar": {
|
||||
"title": "Foo Bar",
|
||||
"owner": "Your GitHub name"
|
||||
}</code></pre>
|
||||
|
||||
|
|
@ -153,22 +159,58 @@ ol.indent {
|
|||
<li>
|
||||
<p>Rebuild Prism by running <code class="language-bash">npx gulp</code>.</p>
|
||||
|
||||
<p>This will make your language available to the <a href="test.html">test page</a>, or more precise: your local version of it. You can open you local <code>test.html</code> page in any browser, select your language, and see how your language definition highlights the given code.</p>
|
||||
<p>This will make your language available to the <a href="test.html">test page</a>, or more precise: your local version of it. You can open your local <code>test.html</code> page in any browser, select your language, and see how your language definition highlights any code you input.</p>
|
||||
|
||||
<p><em>Note:</em> You have to reload the page to apply changes made to <code>prism-lang-id.js</code>.</p>
|
||||
<p><em>Note:</em> You have to reload the test page to apply changes made to <code>prism-foo-bar.js</code>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Write the language definition.</p>
|
||||
|
||||
<p>The <a href="#language-definitions">above section</a> already explains the makeup of language definitions.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Adding aliases.</p>
|
||||
|
||||
<p>Aliases for are useful if your language is known under more than just one name or there are very common abbreviations for your language (e.g. JS for JavaScript). Keep in mind that aliases are very similar to language ids in that they also have to be unique (i.e. there cannot be an alias which is the same as another alias of language id) and work as CSS class names.</p>
|
||||
|
||||
<p>In this example, we will register the alias <code>foo</code> for <code>foo-bar</code> because Foo Bar code is stored in <code>.foo</code> files.</p>
|
||||
|
||||
<p>To add the alias, we add this line at the end of <code>prism-foo-bar.js</code>:</p>
|
||||
|
||||
<pre><code class="language-js">Prism.languages.foo = Prism.language['foo-bar'];</code></pre>
|
||||
|
||||
<p>Aliases also have to be registered in <code>components.json</code> by adding the <code>alias</code> property to the language entry. In this example, the updated entry will look like this:</p>
|
||||
|
||||
<pre><code class="language-js">"foo-bar": {
|
||||
"title": "Foo Bar",
|
||||
"alias": "foo",
|
||||
"owner": "Your GitHub name"
|
||||
}</code></pre>
|
||||
|
||||
<p><em>Note:</em> <code>alias</code> can also be a string array if you need to register multiple aliases.</p>
|
||||
|
||||
<p>Using <code>aliasTitles</code>, it's also possible to give aliases specific titles. In this example, this won't be necessary but a good example as to where this is useful is the markup language:</p>
|
||||
|
||||
<pre><code class="language-js">"markup": {
|
||||
"title": "Markup",
|
||||
"alias": ["html", "xml", "svg", "mathml"],
|
||||
"aliasTitles": {
|
||||
"html": "HTML",
|
||||
"xml": "XML",
|
||||
"svg": "SVG",
|
||||
"mathml": "MathML"
|
||||
},
|
||||
"option": "default"
|
||||
}</code></pre>
|
||||
</li>
|
||||
<li>
|
||||
<p>Add some tests.</p>
|
||||
|
||||
<p>Create a folder <code>tests/languages/lang-id/</code>. This is where your test files will live. The test format and how to run tests is described <a href="test-suite.html">here</a>. A good example are <a href="https://github.com/PrismJS/prism/tree/master/tests/languages/javascript">the tests of the JavaScript language</a>.</p>
|
||||
<p>Create a folder <code>tests/languages/foo-bar/</code>. This is where your test files will live. The test format and how to run tests is described <a href="test-suite.html">here</a>.</p>
|
||||
|
||||
<p>You should add a test for every major feature of your language. Test files should test the common case and certain edge cases (if any). <br>
|
||||
You can use this template for new <code>.test</code> files:</p>
|
||||
<p>You should add a test for every major feature of your language. Test files should test the common case and certain edge cases (if any). Good examples are <a href="https://github.com/PrismJS/prism/tree/master/tests/languages/javascript">the tests of the JavaScript language</a>.</p>
|
||||
|
||||
<p>You can use this template for new <code>.test</code> files:</p>
|
||||
|
||||
<pre><code>The code to test.
|
||||
|
||||
|
|
@ -192,13 +234,13 @@ Brief description.</code></pre>
|
|||
</li>
|
||||
<li>
|
||||
<p>Once you <strong>carefully checked</strong> that the test case is handled correctly (i.e. by using the test page), run the following command:</p>
|
||||
<code class="language-bash">npm run test:languages -- --language=lang-id --pretty</code>
|
||||
<code class="language-bash">npm run test:languages -- --language=foo-bar --pretty</code>
|
||||
<p>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 <em>Token Stream</em>. (Please also adjust the indentation. We use tabs.)</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><strong>Carefully check</strong> that the token stream JSON you just inserted is what you expect.</p>
|
||||
</li>
|
||||
<li>Re-run <code class="language-bash">npm run test:languages -- --language=lang-id --pretty</code> to verify that the test passes.</li>
|
||||
<li>Re-run <code class="language-bash">npm run test:languages -- --language=foo-bar --pretty</code> to verify that the test passes.</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>
|
||||
|
|
@ -208,7 +250,7 @@ Brief description.</code></pre>
|
|||
<li>
|
||||
<p>Add an example page.</p>
|
||||
|
||||
<p>Create a new file <code>examples/prism-lang-id.html</code>. This will be the template containing the example markup. Just look at other examples to see how these files are structured. <br>
|
||||
<p>Create a new file <code>examples/prism-foo-bar.html</code>. This will be the template containing the example markup. Just look at other examples to see how these files are structured. <br>
|
||||
We don't have any rules as to what counts as an example, so a single <em>Full example</em> section where you present the highlighting of the major features of the language is enough.</p>
|
||||
</li>
|
||||
<li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue