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
.
:fire:
|
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'
: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
slug: intro-neo4j-4-0
parent_path: /intro
author:
name: Michael Hunger
first_name: Michael
last_name: Hunger
email: [email protected]
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 :robot: 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:
-
Edit
neo4j-asciidoctor-extensions.gemspec
and update the version numbers.version
-
Run
bundle exec rake
to make sure that everything is working -
Commit both
neo4j-asciidoctor-extensions.gemspec
andGemfile.lock
files -
Tag the version using
git tag vx.y.z
(don’t forget thev
prefix and replacex.y.z
with an actual version) -
Push your changes with the tag:
git push origin master --tags