Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

Alan IF Documentation Project

This repository contains the AsciiDoc sources of the ALAN Documentation published at:

Help and contributions are welcome (see

For a quick overview of the status of the documents in this project, see the document.

SUBMODULES NOTE — This repository contains Git submodules; clone with:

$ git clone --recursive

If you've already cloned it, update via:

$ git submodule update --init

Table of Contents

Latest News

Some important news for project maintainers and contributors...

Adopting Rouge

Since July 2021, this project support syntax highlighting via Rouge (Ruby).

The new Rouge toolchain uses our own custom Rouge adapter and lexer for ALAN, allowing static highlighting supporting callouts (which Highlight doesn't support). All documents that don't make use of span or highlight marker formatting in highlighted code blocks (a feature currently unsupported with Rouge) are migrating from Highlight or highlight.js to the Rouge toolchain.

Migration to Highlight v4

Since May 2021, this project uses the new Highlight v4 version.

Since the new major version introduced some changes in the class names in the generated HTML, we've updated all Sass/SCSS sources accordingly, and Highlight v3.x will no longer work correctly (some elements wouldn't be highlighted as expected).

New Project Website

Since April 2021, this repository now has its own website were you can consult and download all the ALAN documentation:

PDF and HTML builds of the documents will no longer be tracked by the repository (will be ignored by Git), and will only be available through the website.

About This Project

This repository was created on August 15th, 2018 by Tristano Ajmone on behalf of the Alan Interactive Fiction Development team in order to port to the AsciiDoc format the original Alan documentation, which consisted of multiple documents in various formats, and create a unified project and a toolchain to handle their conversion to different formats.

In the course of 2021, after three years of work, we finally achieved the stage where all the documents originally stored in the ALAN repository, as well as some other third party documents, were all successful recreated in AsciiDoc and made available on the project's website for online consultation or download.

Other members of the Alan group are also working on porting other Alan related documents to AsciiDoc, so hopefully this might become a collaborative project to join efforts and resources toward a unified goal.

License Terms

The Alan System is distributed under the Artistic License 2.0, which includes also the documentation that ships with it.

Project Structure and Contents

Git Submodules

Please, be aware of the presence of a Git submodule inside the /alan-xsl-fopub/ folder, and make sure you properly update it in your local clone of the repository to avoid regressions when commiting to the project.

For a tutorial on the common pitfalls of submodules, refer to Christophe Porteneuve's article Mastering Git submodules » The dangers we face.

For detailed info on how to use Git submodules, see:

File Extensions Conventions

In order to distinguish between AsciiDoc documents according to their role in the project, the following file-extensions conventions are being adopted:

  • .asciidoc — used for Alan documentation source files.
  • .adoc — used for sub-sources in multi-file ALAN documents, i.e. imported in the main source via include:: directives.
  • .asc — used for project docs (e.g. READMEs) and any AsciiDoc files not intendend for distribution in the Alan documentation.

Using different extensions is also required for automation scripts, which select sourcefiles by their extension during batch operations.

Development Enviroment Info

This is the environemnt setup used for the project by its maintainer:

ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x64-mingw32]
Asciidoctor 2.0.15
asciidoctor-diagram 2.1.2
Rouge 3.26.0
Asciidoc FX v1.6.8
Dia Diagram Editor v0.97

Syntax Highlighting

This project provides all the required assets to highlight AsciiDoc documents containing ALAN code blocks, using Asciidoctor and a choice of different highlighters, for which Tristano Ajmone has created custom ALAN syntax definitions:

highlighter formats backends
Highlight HTML Asciidoctor
highlight.js HTML Asciidoctor
Rouge HTML/PDF Asciidoctor, asciidoctor-pdf
XSLTHL PDF asciidoctor-fopub

For more info on the various features supported by each highlighter, and how these might affect which highlighter to use for a new document, see the document.

Project Dependencies


In order to convert the AsciiDoc sources to any format you'll need to install Ruby and the Asciidoctor gem.

Once you've installed Ruby, you can install the Asciidoctor gem via CLI:

gem install asciidoctor


The AsciiDoc to PDF toolchain also requires setting up asciidoctor-fopub on your machine; this tool is required to convert from DocBook to PDF.

For guidelines on setting up the asciidoctor-fopub toolchain, refer to documentation of the alan-xsl-fopub submodule:

Also available locally at:

  • _assets/alan-xsl-fopub/

Asciidoctor Diagram

This Ruby gem is an Asciidoctor extension,

Asciidoctor Diagram is a set of Asciidoctor extensions that enable you to add diagrams, which you describe using plain text, to your AsciiDoc document.

It's only required to build some documents in this project, i.e. the ALAN design docs found in:

To install the Asciidoctor Diagram via the CLI:

gem install asciidoctor-diagram

Dia Diagram Editor

Optionally, if you want to edit and build the diagram images, you'll need to install Dia on your machine too. This tool is required to build via automated scripts some images found in /_assets-src/images/.


This is a cross platform application, just download the installer matching your OS and architecture.


You don't need to install anything for documents using highlight.js; the repository contains a custom highlight.js package which is used for syntax highlighting.


Rouge is our syntax highlighter of choice in this project, so you should really install it.

This is a Ruby gem, to install it via CLI type:

gem install rouge

Work Tools

To edit the AsciiDoc documents I'm using both Asciidoc FX and Sublime Text 3 with the Asciidoctor Package.

Asciidoc FX

Asciidoc FX is a cross platform and open source book/document editor to build PDF, Epub, Mobi and HTML books, documents and slides.

This is a great editor for AsciiDoc and offers many useful features for tracking errors and converting to various formats; but most of all it offers an in-editor live-updated HTML5 preview of the document being edited, and also supports in-browser preview with live updates.

Sublime Text Asciidoctor

When it comes to global editing a document or project, Sublime Text offers many powerful features which make it my first-choice editor. So I tend to do all RegEx substitutions work via Sublime Text.

The Asciidoctor package adds to Sublime Text 3 AsciiDoc syntax highlighting.

External Links