prism-plugin-ext demo

This is a GitBook book that demonstrates how to configure and use the gitbook-plugin-prism-ext plugin effectively.

Introduction

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 and this demo book, not only provides those styles, but it also demonstrates how to setup your book's book.json and provides some examples of the plugin being used to highlight a few code blocks, using different Prism plugins.

Installation

First, make sure you have GitBook's command line interface installed.

Clone this repository to a directory on your machine and then, using your terminal, run:

cd the-prism-plugin-ext-demo-directory
gitbook install
gitbook serve

Now you can view the book on your browser at http://localhost:4000.

The same page you're reading right now should appear, with the difference that the highlighting examples below will be properly highlighted.

Configuration

Please study this project's book.json file, which contains a valid demo configuration, and the source code of this README.md document.

Feel free to use the bundled custom.js and custom.css files on your own books, or just parts of them.

The custom.js Prism plugin is a demo of how to create your own plugins that you may include on your books. This specific plugin demo just suppresses line numbers when the code block has a single line.

The custom.css file demonstrates how to include your own stylesheets on your books, using the prism-ext plugin. You will usually need some of the styles it provides for the plugin to work properly on your books.

Applying line-numbers to all blocks

If you want to apply the line-numbers class to all code blocks on your book, without having to use the {.line-numbers} syntax on each block, you should set the following option on book.json:

{
  "pluginsConfig": {
    "prism": {
      "cssClasses": "line-numbers"
    }
  }
}

Syntax highlighting examples, using Prism

Note: you should view the following examples on http://localhost:4000 using the gitbook serve command.

Some PHP code with the line-numbers plugin

use Matisse\Components\Base\Component;

class HelloWorld extends Component
{
  protected function render ()
  {
    echo "Hello World!";
  }
}

This code block begins with the following syntax, which applies the line-numbers CSS class to the block, enabling the display of line numbers:

```php{.line-numbers}

The following options on book.json should be set:

{
  "pluginsConfig": {
    "prism": {
      "codeBlockExtSyntax": true
    }
  }
}

Example with both the line-numbers and the line-highlight plugins

<h1>Some HTML text</h1>
<HelloWorld/>
<form>
  <Input name=field1 value={myVar}/>
  <For each=record of={data}>
    <Header><ul></Header>
    <li>Item {record.name}</li>
    <Footer></ul></Footer>
    <Else>There are no items.</Else>
  </For>
</form>

This code block should be defined with the following line:

```html{.line-numbers data-line="2,4-5,10"}

The following options on book.json should be set:

{
  "pluginsConfig": {
    "prism": {
      "codeBlockExtSyntax": true,
      "lineHeight": 20
    }
  }
}

License

You can use this book template freely, for any purpose, with no copyright or legal restrictions of any kind.

The complete license can be read at unlicense.org.