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

Update documentation for node & webpack usage #1429

Merged
merged 1 commit into from
May 31, 2018
Merged

Update documentation for node & webpack usage #1429

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
35 changes: 25 additions & 10 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,14 +153,28 @@ <h1>Basic usage</h1>
Example:</p>
<pre><code>&lt;script src="prism.js" data-manual>&lt;/script></code></pre>

<p>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 <a href="https://www.ampproject.org/">AMP pages</a>.</p>
<h2>Usage with Webpack, Browserify, & Other Bundlers</h2>

<p>You can install Prism for Node.js by running:</p>
<pre><code>$ npm install prismjs</code></pre>
<p>If you want to use Prism with a bundler, install Prism with <code>npm</code>:</p>

<p>Example:</p>
<pre><code class="language-js">var Prism = require('prismjs');
<pre><code>$ npm install prismjs</code></pre>

<p>You can then <code class="language-js">import</code> into your bundle:</p>

<pre><code class="language-js">import Prism from 'prismjs';</code></pre>

<p>To make it easy to configure your Prism instance with only the languages and plugins you need, use the babel plugin,
<a href="https://github.com/mAAdhaTTah/babel-plugin-prismjs">babel-plugin-prismjs</a>. This will allow you to load
the minimum number of languages and plugins to satisfy your needs.
See that plugin's documentation for configuration details.</p>

<h2>Usage with Node</h2>

<p>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 <a href="https://www.ampproject.org/">AMP pages</a>.</p>

<p>Example:</p>
<pre><code class="language-js">var Prism = require('prismjs');

// The code snippet you want to highlight, as a string
var code = "var data = 1;";
Expand All @@ -169,13 +183,12 @@ <h1>Basic usage</h1>
var html = Prism.highlight(code, Prism.languages.javascript, 'javascript');</code></pre>

<p>Requiring <code>prismjs</code> will load the default languages: <code>markup</code>, <code>css</code>,
<code>clike</code> and <code>javascript</code>. You can load more languages separately by requiring them
directly from the <code>components</code> folder. Or you can use the <code class="language-javascript">loadLanguages()</code> utility, that
will automatically handle any required dependencies.</p>
<code>clike</code> and <code>javascript</code>. You can load more languages with the
<code class="language-javascript">loadLanguages()</code> utility, which will automatically handle any required dependencies.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to remove any reference to manual requiring? I mean it can still be useful, for example to load a custom language definition.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My approach was to, for both bundlers & Node, give them One True Way™ to load Prism, to reduce confusion about how they should go about it. My assumption / expectation was manual requiring is what people are going to try before reading the documentation and I don't want to encourage manual requiring of language definitions so we don't repeat what happened in 1.14.0 with the markup-templating change. Now that we've got solutions for handling internal language dependencies, we should be pushing people to use them.

<p>Example:</p>

<pre><code class="language-js">var Prism = require('prismjs');
var loadLanguages = require('prismjs/components/index.js');
var loadLanguages = require('prismjs/components');
loadLanguages(['haml']);

// The code snippet you want to highlight, as a string
Expand All @@ -184,6 +197,8 @@ <h1>Basic usage</h1>
// Returns a highlighted HTML string
var html = Prism.highlight(code, Prism.languages.haml, 'haml');</code></pre>

<p><strong>Note</strong>: Do <em>not</em> use <code class="language-javascript">loadLanguages()</code> with Webpack or another bundler, as this will cause Webpack to include all languages and plugins. Use the babel plugin described above.</p>

</section>

<section id="languages-list" class="language-markup">
Expand Down