AsciiDocGen

AsciiDocGen is a Perl application that will allow you to maintain a web site written entirely in AsciiDoc. This allows you to take advantage of AsciiDoc to manage all the content for your web site, without having to worry about html creation or transfering your files to your web server. AsciiDocGen automatically determines what source files have changed, generates appropriate html files, and transfers the resulting html directly to your web site.

This website is maintained using AsciiDocGen. AsciiDocGen has been tested on both Mac and Windows.

Mac Logo Windows Logo

How It Works

Install two files, asciidocgen.pl and asciidocgen.conf, into the root folder of your website on your local computer. Whenever you make a change to your source content, run asciidocgen.pl and your remote website will be updated automatically.

AsciiDocGen is very simple. Just put your template html file in the root folder of your website and all pages will be created using that template. You include a simple html comment in your template, and all of your page content will be inserted into the template at that location. See the template provided with AsciiDocGen for an example.

Installation

Download the zip archive, uncompress and place the two files into the root folder of your local website. Modify the conf file to reflect your local and remote website settings, then begin publishing. AsciiDocGen is template driven. You will need to provide a page template of your own design. There are many good free templates available on the internet. This site uses a free template created by Andreas Viklund.

Configuring AsciiDocGen

To get up and running with AsciiDocGen, all you need to do is modify the configuration file, asciidocgen.conf with the settings for your local and remote sites. This file is very straightforward, the file used to maintain dbixjcl.org is shown below.

local:
    tz:                PDT
    tzlong:            Pacific Daylight Time
    process_filename:  _process
    template_filename: _template
    category_filename: _category
    copy_filename:     _copy
    localroot:         /Users/badkins/asciidoc/dbixjcl
    asciidocpath:      /usr/local/bin/asciidoc.py

web:
    webserver:   dbixjcl.org
    webuser:     yourusername
    webpassword: yourpassword
    webroot:     /jcl

category: JCL

supplemental_footer: |
    <div id="footer">
    <div id="footer-text">
    Last updated $current_time
    </div>
    </div>

A couple of things should be noted. The path entries do not end with a slash, nor does the webroot entry. The webroot entry is the folder under the root level folder where your project is homed. It’s good practice not to use your web root folder as the starting folder for your project. Note that the webroot entry begins with a slash.

You define a supplemental footer if you want each page to have some standard content inserted following your page content. This does not have to contain a current date, if it does, use the variable $current_time to indicated where the current date and time should be placed in your footer html.

Running AsciiDocGen

All it takes to update your website is the following command. You should first cd into your local webroot folder, where you have also installed asciidocgen.pl and asciidocgen.conf.

>perl asciidocgen.pl

There are a few options available when running AsciiDocGen, these are described in the table below.

Command Line Options
Option Description

-forceasciidoc

force all AsciiDoc files to be updated

-forcenonasciidoc

force all Non-AsciiDoc files to be updated

-silent

do not display progress to stdout

-nofooter

no footer added to content

-help

this help

Options may be abbreviated to uniqueness.

Additional Features

Category File

Each of your generated pages can have a category displayed if you use the category tag in your template. The category tag is a simple html comment, wherever it occurs in your template, it will be replaced with the category entry from the conf file or from whatever has been entered into the category file in that directory. This will allow you to provide a description for groups of pages. See the template provided for an example. You define the name of your category file in asciidocgen.conf.

Copy File

Using copy files will allow asciidocgen.pl to manage non-text files. Any directory can contain a copy file. The copy file simply contains a list of files that should be transferred whenever they have been updated. Currently .jpg, .gif, and .png files are supported by the copy functionality. You define the name of your copy file in asciidocgen.conf.

History

Version 1.01, Wed Jun 9 2009

  • Add category content from a category file

  • Create a process file if one does not exist

  • Create remote directory when necessary

Version 1.00, Tue Jun 1 2009

Initial release.

Enhancements

Please contact the author if you have enhencement suggestions.

License

AsciiDocGen is free software released under the terms of the Artistic License 2.0.

I hope you enjoy using AsciiDocGen.