ASCIIDoc/ASCIIDoctor: The easiest way to use it on Windows

Helpinator allows to generate ASCIIDoc source file (with .adoc extension) that you can use in your ASCIIDoctor documentation toolchain or just employ to create HTML using beautiful templates that this generator provides. In any way you need to install ASCIIDoctor on your Windows system and given it’s Ruby origins it may become quite a task for a novice.

Good news is that there’s a JS-port of ASCIIDoctor that you can install via npm (node package manager) and use from the command line. Here are the steps.

1. Download Node.Js dsitribution package from https://nodejs.org. It’s better to choose installer over other variants, because it will execute all required tasks like adding node to the PATH variable automatically.

2. Run the installer and follow the instructions. It’s better to choose the path outside of Program Files folder.

Node.js installer
Set path for node.js

Finish the installer and reboot your machine just in case.

Now you have Node Package Manager on your system and you can use it to install ASCIIDoctorJS.

3. Open command prompt and change current path to C:\nodejs (the folder where node.js resides on your system).

Now let’s install ASCIIDoctor via command line using npm:

npm i asciidoctor --save
npm i -g asciidoctor.js asciidoctor-cli

This will create asciidoctorjs.cmd file in node.js folder that will be available from command line.

4. Now let’s produce some ASCIIDoc sources from our Helpinator project. Select Main Menu -> Tools -> Batch Compile and add “ASCIIDoc” output, then specify folder path to save output to.

Batch job to compile ASCIIDoc

Click on lightning bolt icon and Helpinator will create .adoc file and images folder in the path specified.

Now we can get back to command line, change current folder to C:\Project\Help\ASCIIDoc and run asciidoctorjs to create HTML5 file from “Helpinator.adoc” file generated by Helpinator:

asciidoctorjs Helpinator.adoc

You will see generated .html file next to your .adoc file when the command finishes execution. Open it and enjoy impressive design work done for ASCIIDoc.

If you are too lazy to follow the procedure above, there’s a compiled source file of Helpinator help system in ASCIIDoc format on the “Download” page under “Sample Documentation” section.

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.