Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Create a Custom Neo4j Browser Guide

Create a Custom Neo4j Browser Guide


With version Neo4j 2.3 we introduced the ability to run custom "slide-shows" in the Neo4j Browser, similar to the existing :play movie graph.

The idea behind these guides is, that you can provide a guided tour to a data set or use-case. Your users can interactively read through the slide-show, execute statements to import or query the data or look at pictures, videos or other media for detailed explanations.

We use these guides ourselves in many areas:

Others have used them too, here a few examples:

Technical Background

Those guides are simple HTML pages with a section per slide. Your users can interactively read through the slide-show, execute statements from <pre/> areas to import or query the data or look at pictures, videos or other media for detailed explanations. Of course you can use other HTML elements like tables, bullets, links etc. There are some special classes that trigger actions within Neo4j Browser, e.g. for :play or :help commands.

Since Neo4j 3.1 it is also possible to provide form-fields whose input is automatically included in the query text.

The guides can be hosted anywhere, for security reasons you have to whitelist any domain besides in your $NEO4J_HOME/conf/neo4j.conf.

# comma separated list of base-urls, or * for everything

Your server has to support proper CORS headers for both GET and OPTIONS requests, so unfortunately GitHub pages and Dropbox folders don’t work, but s3 works well enough (or a custom Python or Java webserver).

For security reasons Javascript and Angular tags are stripped from the HTML, even from whitelisted sources.
If your Neo4j instance is access over a 'https://' URL, only guides hosted on 'https://' URLs will render. Currently, as of 14-Mar-2017, does not support 'https'.

Slide Format and Creation

The HTML format is described in detail here, but don’t despair, you don’t have to create the HTML manually, although you can fine tune the generated HTML from the next step afterwards.

To make it easier to create Browser Guides we created a simple tooling repository that uses AsciiDoc as source format and a HTML template with the slide structure.

AsciiDoc is used in many places, e.g. for O’Reilly books, many Documentation Manuals (ours too), our [GraphGists] but also Readme’s and Wiki’s on GitHub. It was developed for technical documentation, and is more powerful than Markdown. You can find a basic syntax overview here.

We use the AsciiDoctor toolchain and a variant of its erb-HTML5 templates.

Our process is straightforward. Just find or create a simple AsciiDoc file (see below) and convert it to the slide-html. Each second-level header is turned into a new slide, and [source,cypher] blocks into clickable statements. Otherwise all regular HTML transformations apply. For deep details on the AsciiDoc syntax, please see the AsciiDoctor User Manual

Concrete Example

Clone and enter this repository and start editing your first guide.

git clone
cd neo4j-guides
edit adoc/test.adoc
= A Test Guide

== First Slide: Media


This is just a test guide.

But it comes with a picture and a video:

<iframe width="560" height="315" src="" frameborder="0" allowfullscreen></iframe>

== Second Slide: Statements

=== Creating Data

The area below becomes a clickable statement.

CREATE (db:Database {name:"Neo4j"})

=== Querying Data
:name: pass:a['<span value-key="name">Neo4j</span>']

We use a form field here:

<input style="display:inline;width:30%;" value-for="name" class="form-control" value="Neo4j" size="40">

MATCH (db:Database {name:{name}})

== Third Slide: Links

*[Learn more about Cypher]
* pass:a[<a help-topic='key'>Help Keys</a>]
* pass:a[<a play-topic=''>Another Guide</a>]


And then run it through the script to convert it to the HTML slides.

./ adoc/test.adoc html/test.html

# optional arguments, leveloffset to change the heading level up or down, base-url and additional attributes

./ path/to/test.adoc path/to/test.html [+1]

# then upload the file to your target server, e.g.

s3cmd put -P html/test.html s3://


  • idea

  • built in guides

  • capabilities

  • format

  • hosting

  • whitelist

  • auto-play command

  • url-param cmd=play&args=

Creating Process

  • AsciiDoc to Guide

    • 2nd level header to slide

    • cypher code blocks

    • tables, bullets, images

    • javascript / angular attributes are stripped from the HTML source

    • iframes are possible

    • automatic form fields

  • neo4j-guides repository

AsciiDoc to Guide

Guide Generator ADOC→ Guides

Guide from GDOC

Create a google document with AsciiDoc content for collaborative editing. Make it publicly readable - "everyone with link can read". Get the file / URL from "Download as Plain Text" and render to a Guide like we did before.

curl -sL "$url" -o adoc/$name.adoc
./ adoc/$name.adoc html/$name.html
s3cmd put -P html/$name.html s3://$name

Example Collection

Beer Graph Guide - Rik Van Bruggen

TODO picture / video

Rik van Bruggen demonstrates in detail how to turn a data set or GraphGist into a proper Browser Guide.


The APOC procedure library comes with a lot of useful functionality for Neo4j. For an "interactive" manual, some of the original documentation was turned into guides.


TODO link to network / sandbox


Twitter Election Graph :play

Exploring Shipping Data

Graphs in Data Journalism:

Graphs in Data Journalism: :play


Game of Thrones Guide Will Lyon:

TODO text, link to blog posts, link to trumpworld-graph repo



TODO text, link to blog posts, link to trumpworld-graph repo


Legis Graph:

TODO blog posts / repo


Short Term Rental Listings (AirBNB)



TODO link / url

Panama papers guide

TODO blog post / screen shot

Need to whitelist source.


GraphGist Portal allows any GraphGist to be viewed as a Guide.

"Run this gist in the Neo4j console"
Need to whitelist source.

Select GraphGists: :play

Graph-Commons Also you’ve probably seen it, Graph Commons supports the Neo4j browser, you can simply type this below in the Neo4j browser (notice the /neo4j at the end): :play

Need to whitelist source.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment