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

Extending page: Fixed typo + new alias section #1949

Merged
merged 1 commit into from
Jun 29, 2019
Merged

Extending page: Fixed typo + new alias section #1949

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
66 changes: 54 additions & 12 deletions extending.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,16 +133,22 @@ <h2>Parameters</h2>
<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&trade;</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>

Expand All @@ -153,22 +159,58 @@ <h1>Creating a new language definition</h1>
<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). 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 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 can use this template for new <code>.test</code> files:</p>

<pre><code>The code to test.

Expand All @@ -192,13 +234,13 @@ <h1>Creating a new language definition</h1>
</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>
Expand All @@ -208,7 +250,7 @@ <h1>Creating a new language definition</h1>
<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>
Expand Down