gitbook-plugin-lilypond-highlight

lilypond-highlight is a Gitbook plugin that produces syntax-highlighting for LilyPond code fragments. It makes use of the python-ly package, which is therefore an external dependency. In the future it will also be possible to access a remote server running python-ly, but that should only be a fallback solution as there will surely be substantial performace issues with that approach.

Installation

To use the plugin simply add it to the plugin list in your book.json:

...
},
"plugins": [
    "lilypond-highlight",
    "other-plugins"
    ],
...

and then run gitbook install in your project directory. This should also install some node module dependencies.

python-ly

python-ly is a Python package with many tools to process LilyPond input. It is the source-code handling “backend” of Frescobaldi, the LilyPond IDE. To communicate with python-ly the lilypond-hihglight plugin makes use of the ly-client npm package, which is implicitly installed. But python-ly has to be installed separately:

pip install python-ly

(using sudo if appropriate on your system. It is also possible to install python-ly through its Git repository, but that will require some extra work to set up paths.)

To check if python-ly is properly accessible try to run

ly --help

from anywhere, which should correctly print the help information.

Stylesheet

The plugin creates syntax highlighting by marking the input with <span> elements. For these to make a visual difference the accompanying stylesheet has to be used. We hope to include that stylesheet automatically but for now you will have to do that on your own. Copy the file styles/ly.css to your Gitbook directory (e.g.) in a styles directory and add that to your book.json. For example simply like this:

"styles": {
    "website": "styles/ly.css",
},
 

For any further complexities please consult the Gitbook documentation.

Usage

This plugin exposes two command that allows inserting LilyPond code:

{% lilypond %}
Insert arbitrary LilyPond code,
this will produce a block style code example.
{% endlilypond %}

{% lilycode %}
Insert arbitrary LilyPond code,
this will produce an inline code snippet.
{% endlilypond %}