Neo4j Asciidoctor Extensions

This repository contains Asciidoctor extensions made by Neo4j for processing and publishing AsciiDoc content.

Install

$ gem install neo4j-asciidoctor-extensions

Usage

CLI

$ asciidoctor -r neo4j/asciidoctor/extensions doc.adoc

API

require 'neo4j/asciidoctor/extensions'

In addition, you can require individual extension:

require 'neo4j/asciidoctor/extensions/revealjs_linear_navigation'

See below for the complete list of extensions.

Extensions

The Ruby gem contains 6 distinct extensions:

Neo4j course attributes

A postprocessor that adds attributes about a course on the Document.

🔥	This extension is tightly coupled to the course publishing project and should not be used for other purposes

require 'neo4j/asciidoctor/extensions/course_document_attributes'

Cypher syntax role

A tree processor that adds a role on code blocks using "cypher-syntax" as a language.

Usage

require 'neo4j/asciidoctor/extensions/cypher_syntax_role'

[source,cypher-syntax]
----
()
(p)
(l)
(n)
----

Metadata generator (YAML)

A postprocess that generates a metadata file (in YAML format) from a list of document attributes.

Usage

require 'neo4j/asciidoctor/extensions/document_metadata_generator'

file.adoc

:document-metadata-attrs-include: author,slug,parent-path,tags*,taxonomies*<>
:tags: intro,course
:taxonomies: os=linux,programming_language=java,neo4j_version=3-5;3-6
:slug: intro-neo4j-4-0
:parent_path: /intro

file.yml

slug: intro-neo4j-4-0
parent_path: /intro
author:
  name: Michael Hunger
  first_name: Michael
  last_name: Hunger
  email: michael.hunger@neotechnology.com
tags:
  - intro
  - course
taxonomies:
  - key: os
    values:
      - linux
  - key: programming_language
    values:
      - java
  - key: neo4j_version
    values:
      - 3-5
      - 3-6

Inline syntax highlighter based on Rouge

Inline syntax highlighter based on Rouge. It applies syntax highlighting on both monospaced text cypher and src inline macro:

Usage

require 'neo4j/asciidoctor/extensions/inline_highlighter_rouge'

[src-cypher]`MATCH (c:Customer {customerName: 'ABCCO'}) RETURN c.BOUGHT.productName`

src:cypher[MATCH (c:Customer {customerName: 'ABCCO'}) RETURN c.BOUGHT.productName]

Linear navigation for reveal.js

A tree process that "flatten" a reveal.js presentation to use a linear navigation. By default, the reveal.js converter will use a vertical navigation for the second levels of section titles (and below). This extension will effectively prevent that by using only first level section titles.

Usage

require 'neo4j/asciidoctor/extensions/revealjs_linear_navigation'

Notes aggregator for reveal.js

A tree processor that aggregates multiple [.notes] blocks in a section (slide).

Usage

require 'neo4j/asciidoctor/extensions/revealjs_speaker_notes_aggregator'

== Introduction

[.notes]
--
This is a speaker note.
--

Hello!

[.notes]
--
This is another speaker note.
--

Document attribute update

A tree processor that update an attribute depending on a given rule.

Usage

In the example below, we update the value of the slug attribute depending on the stage attribute:

require 'asciidoctor/extensions'
require 'neo4j/asciidoctor/extensions/attribute_update/extension'

Asciidoctor::Extensions.register do
  ext = Neo4j::AsciidoctorExtensions::AttributeUpdateTreeProcessor
  tree_processor ext.new attr_name: 'slug',
                         update_rule: lambda { |document, value|
                           case document.attr('stage')
                           when 'production'
                             value
                           when 'development'
                             "_dev_#{value}"
                           else
                             "_test_#{value}"
                           end
                         }
end

Release

The release process is automated and relies on GitHub Actions. We are using the 🤖 neo4j-oss-build account to publish on https://rubygems.org/gems/neo4j-asciidoctor-extensions.

The RUBYGEMS_API_KEY secret is configured on GitHub. See the .github/workflows/release.yml file for details.

The release will be performed when a tag is pushed, the procedure is:

1. Edit neo4j-asciidoctor-extensions.gemspec and update the version number s.version

2. Run bundle exec rake to make sure that everything is working

3. Commit both neo4j-asciidoctor-extensions.gemspec and Gemfile.lock files

4. Tag the version using git tag vx.y.z (don’t forget the v prefix and replace x.y.z with an actual version)

5. Push your changes with the tag: git push origin master --tags