Introduction

The AsciiDoc NetBeans plugin is designed to support the publishing of AsciiDoc files using the asciidoctor and asciidoctor-pdf.

In non Project Mode, it provides a publish action for any .adoc file, which can create either an html or pdf document (depending upon the header of the document). The resulting file will be placed in the same folder as the .adoc file.

Publishing actions are in the file node’s popup actions, and also in the editor window’s popup actions.

The NetBeans spelling checker is enabled when editing an AsciiDoc file.

In Project Mode, an AsciiDoc Project is recognised by the presence of an asciidoc.properties file at the root level of the project. There will also be a folder at the root level (named src) which will contain the asciidoc files which make up the project and their associated resources. Any folder structure within the src folder is acceptable. All .adoc files will have a publishing action. The published documents will be placed within another root level folder (named generated_documents). This will include a folder structure that reflects the source folder structure.

AsciiDoc projects are suited to publishing an assembly of AsciiDoc files and/or repurposing documents so that they can be published in multiple formats. Alternatively they can be used as containers for a collection of individual documents.

Caution
 The predefined .adoc file actions are limited to Unix family systems (i.e. Linix and MacOS). No Windows implementation have yet been completed.

AsciiDoctor NB-Plugin by Example

AsciiDoc file recognition

Any AsciiDoc file (.adoc) will be recognised by NetBeans and will have a Publish action included in it’s popup menu.

basic publish action

If the file is not located within a AsciiDoc project then the Publish action will create the published document in a same folder as the source.

basic folder structure

Publish a pdf article

To publish an asciidoctor-pdf article your AsciiDoc file will need to define options in it’s header

:doctype: book
:backend: pdf
:toc: (1)
:revnumber: 2.0.2 (1)
:revremark: Early Preview Edition (1)
:version-label: Release (1)
= AsciiDoc NetBeans Plugin User Guide

  1. optional options

Publish an html article

To publish an asciidoctor article your AsciiDoc file will need to define options in it’s header

:toc2: (1)
:revnumber: 2.0.2 (1)
:revremark: Early Preview Edition (1)
:version-label: Release (1)
= AsciiDoc NetBeans Plugin User Guide

  1. optional options

To repurpose an AsciiDoc file for both pdf and html publishing

To repurpose a file to publish in multiple formats, create 3 files - the source file (without headers) and two files which contain the necessary headers and an include statement to add the source.

source folder structure

In book.adoc set the options for a book and an include statement.

:doctype: book
:backend: pdf
:toc:
:revnumber: 2.0.2
:revremark: Early Preview Edition
:version-label: Release
= AsciiDoc NetBeans Plugin User Guide

include::introduction.adoc[]

Select Publish on the book.adoc file to create the pdf.

book action

In web.adoc set the options for an html document and an include statement. Select Publish on the web.adoc file to create the html.

:toc2:
:revnumber: 2.0.2
:revremark: Early Preview Edition
:version-label: Release
= AsciiDoc NetBeans Plugin User Guide

include::introduction.adoc[]

The resulting folder structure which will contain the two published documents:

folder structure

The project structure

The project structure that is recognised by this plug-in is:

  • an asciidoc.properties file (no content is required).

  • asciidoc files, located within the src folder

  • resources (images etc) to be used in the Publishing process

project structure

The publishing process will create a generated_documents folder.

project structure with published

There are no specific project level Actions.

The standard output and error streams are routed to the NetBeans Output Window, while the published document is created in the generated_documents folder.

To assemble multiple AsciiDoc files for pdf and/or html publishing

One of the major use cases for an AsciiDoc project is to be able to assemble multiple AsciiDoc source files into a book and/or html file.

Using similar techniques seen in previous examples, an AsciiDoc file for each output is created, defining the options, and now a series of include statements define the assembly order.

:doctype: book
:backend: pdf
:toc:
:revnumber: 2.0.2
:revremark: Early Preview Edition
:version-label: Release
= AsciiDoc NetBeans Plugin User Guide

include::introduction.adoc[]

include::example.adoc[]

include::availability.adoc[]

or if you have the source in a subfolder structure.

:doctype: book
:backend: pdf
:toc:
:revnumber: 2.0.2
:revremark: Early Preview Edition
:version-label: Release
= AsciiDoc NetBeans Plugin User Guide

:imagesdir: part1/
include::part1/introduction.adoc[]

include::part1/example.adoc[]

:imagesdir: part2/
include::part2/availability.adoc[]

and html version

:toc2:
:revnumber: 2.0.2
:revremark: Early Preview Edition
:version-label: Release
= AsciiDoc NetBeans Plugin User Guide

include::part1/introduction.adoc[]

include::part1/example.adoc[]

include::part2/availability.adoc[]

Using the AsciiDoc NBM

Adding the NBM to NetBeans

To be able to use the Plugin it must be downloaded and then installed in NetBeans.

Releases of this product are stored in a Maven repository on GitHub. It is possible to download an NBM from Packages.

Once you have a downloaded copy on your machine, you follow the standard NetBeans process to install the downloaded file (Tools>Plugins).

The ActionsSupport NBM must be installed with or prior to installing this NBM.

Useful Links

  • Releases are stored in a Packages Maven repository on GitHub

  • Source Code is stored in a Git repository on GitHub as part of a monorepro containing NBMs.

  • Documentation can be found on the TRP website.

  • Documentation source is stored in a Git repository on GitHub as part of a monorepro containing documentation.

  • Development Process Guide for The-Retired-Programmer products can be found on the TRP website.