Prism with support for Prism plugins
GitBook plugin forThis plugin hilights the syntax of code blocks using the Prism highlighter.
Rendering is performed at build time, NOT at runtime on the browser. This allows the plugin to also run when generating PDF books.
Prism plugins are also supported but, as rendering is done at build time, plugins that generate interactive elements will not work properly; they will render (even for PDFs), but no interactivity is supported.
Technical note: supporting Prism plugins on GitBook is not trivial, as they were designed for operation on the browser only, so a DOM representation of the document must be provided to them. This plugin provides such DOM trough an emulation that runs on NodeJS at build time, so that plugins operate as expected.
Before
After
Usage
Add the plugin to your book.json
, and disable default GitBook code highlighting:
Important
Out-of-the-box, the prism-ext plugin will not work as expected, due to the default CSS styles of GitBook books. Some custom styles are needed to make it work correctly.
See the demonstration project, which provides the required styles.
Demonstration
The easiest, fastest and simplest way to see this plugin working properly is to install the gitbook-prism-ext-demo, which is provided on a separate repository.
Options
theme
Override the default syntax highlighting styles.
The CSS file path may be relative to the node_modules
folder or to the book's source folder (if you want to provide a custom style that is bundled with the book's files instead of being provided by an installable module).
Example:
"pluginsConfig":
lang
Support non-standard syntax prefixes by aliasing existing prefixes.
Example:
"pluginsConfig":
ignore
Due to other plugins using code block notion to denote other functionality, you can ignore certain langs
Example:
"pluginsConfig":
cssClasses
Appends a space-separated list of CSS classes to each fenced code block (those whose PRE element has a CODE element as a direct child).
This is meant to be used with some plugins that require a specific CSS class to be applied to the PRE element, in order for the plugin to be activated on that block.
Example:
"pluginsConfig":
codeBlockExtSyntax
If true
, enables an extended Markdown syntax for fenced code blocks, which allows you to set CSS classes and HTML attributes on the respective HTML <pre>
elements.
The default value is false
.
Example:
"pluginsConfig":
Some Prism plugins require this feature to be enabled, because they are configured view CSS classes or HTML attributes.
Extended Mardown syntax for fenced code blocks
```language{.class1.class2[...].classN attr1="value1" [...] attrN="valueN"} source code```
The syntax definition above means that you may:
- optionally specify an arbitrary number of CSS classes;
- optionally specify an arbitrary number of HTML attributes.
The [...]
represents a repetition of the previous element.
Note that attribute values must be double quoted.
language
is the name of the programming language (ex: javascript
) and it may be ommited.
line-highlight
and line-numbers
plugins
Example of a fenced code block that uses the ```php{.line-numbers data-line="3,5-8"}
use Components\Component;
class HelloWorld extends Component
{
protected function render ()
{
echo "Hello World!";
}
}
```
plugins
An array of strings containing a list of names of Prism plugins to load.
Each element of the array may be either:
- a string with the name of one of the built-in Prism plugins;
ex: "line-numbers"
- an array of CSS and/or JS files for loading a 3rd party or custom plugin.
Each file path may be relative to
node_modules
or to the book's source folder.
Example:
See the section below titled "Prism Plugins".
Prism Plugins
You may specify a list of Prism plugins on the pluginsConfig.prism.plugins
configuration property on book.json
.
See the explanation of the
plugins
option above.
The simplest case
In this basic example, we're loading the line-numbers
Prism plugin.
book.json
Note: the
cssClasses
value is required by this specific Prism plugin.
A more complex case
In this example, we're loading:
- the
line-numbers
andshow-invisibles
Prism plugins, - a custom syntax theme from the
prism-ASH
GitBook plugin, - a custom Prism plugin embedded on the book itself, on the
src
folder, comprised of a CSS and a JS file.
book.json
Supported Prism plugins
Prism plugin | Compatible |
---|---|
autolinker | not tested yet |
autoloader | not tested yet |
command-line | not tested yet |
copy-to-clipboard | not tested yet |
custom-class | not tested yet |
data-uri-highlight | not tested yet |
file-highlight | not tested yet |
highlight-keywords | not tested yet |
ie8 | not tested yet |
jsonp-highlight | not tested yet |
keep-markup | not tested yet |
line-highlight | Yes (with limitations) |
line-numbers | Yes |
normalize-whitespace | not tested yet |
previewer-angle | not tested yet |
previewer-base | not tested yet |
previewer-color | not tested yet |
previewer-easing | not tested yet |
previewer-gradient | not tested yet |
previewer-time | not tested yet |
remove-initial-line-feed | Yes |
show-invisibles | Yes |
show-language | Yes |
toolbar | not tested yet |
unescaped-markup | not tested yet |
wpd | not tested yet |
If you have feedback on this matter (either success or insuccess with specific plugins), please open an issue on GitHub.
Unsupported Prism plugins
Unfortunately, some Prism plugins were just not designed for use in an environment that is not a web browser and make use of browser features that are not easily emulated.
An example of such a plugin is the line-highlight
plugin. It requires a browser for computing the line height, in pixels, of each source code line.
We cannot emulate that on Node.js, when the book is being built (it would require a true CSS rendering engine), so the computed line height is always a fixed, pre-set value, and the highlights will not display correctly.
There are three workarounds for this problem:
- Use an alternative plugin, installed via npm, that is compatible.
- Copy the unsupported plugin to your book and modify it to make it compatbile.
- Create your own plugin and either include it on your book or publish it on npm and install it.
To load a custom plugin from files on your book, see the explanation of the
plugins
option above.
The line-highlight plugin
As a bonus, I've provided a workaround to make this plugin sorta work: the "secret" lineHeight
configuration option.
Place this option on book.json
with the line height, in pixels, of your fenced code blocks. The default value is 17.85
.
book.json example
Markdown example
```php{data-line="3,5-8"}
use Components\Component;
class HelloWorld extends Component
{
protected function render ()
{
echo "Hello World!";
}
}
```
With a little tweaking, you may see something like this:
On this example, I'm using the prism-base16-tomorrow.light
theme.
The line numbers column from the line-numbers
plugin is placed (via CSS) above the line numbers generated by the line-highlight
plugin, so it hides them.
As for the CSS being applied, the font-family is Menlo
, font size is 11.9px
and line-height is 17.85px
. The <pre>
has position:relative
and <code>
has display:block
. The value for lineHeight
on book.json
is 17
.
Unfortunately, all of this only works if the user doesn't increase or decrease the text size when reading the book. This is a limitation of the line-highlight
plugin that cannot be overcome, as it works in pixels only (not on em
or other relative units).
A complete solution would require the original plugin to be forked and patched, or using another plugin, or applying the current plugin on the client-side (the browser) when the book is being viewed; but then, it would no longer work on PDFs.
If anyone knows of an alternative Prism plugin, or makes one, please let me know and I'll mention it here.
Prism Themes
https://github.com/PrismJS/prism
prismjs/themes/prism-okaidia.css
Okaidia prismjs/themes/prism-solarizedlight.css
Solarized Light prismjs/themes/prism-tomorrow.css
Tomorrow prismjs/themes/prism-dark.css
Dark prismjs/themes/prism-coy.css
Coy Atelierbram Themes
https://github.com/atelierbram/syntax-highlighting
syntax-highlighting/assets/css/prism/prism-base16-ocean.dark.css
Base16 Ocean Dark syntax-highlighting/assets/css/prism/prism-base16-google.light.css
Google Light syntax-highlighting/assets/css/prism/prism-xonokai.css
Xonokai Credits
Based on gaearon/gitbook-plugin-prism, which was based on google_code_prettify.
License
Apache 2