William Jeffrey RankinWriting, Design & Miscellany

Projects / Hua

Hua Basics

Hua (simplified Chinese for flower) is a simple, feature-rich, static content generator useful for maintaining web sites and blogs with templates.

Hua was originally written in the Ruby scripting language and was inspired in part by the venerable Perl-based blogging tool Blosxom and similar static content generators. It has since been rewritten in PowerShell. Simplicity is one of its core principles: The database containing site entries, site content, includes, and template files are all maintained in plain text. Comments are provided through a through a third-party engine like Disqus or IntenseDebate. Hua is open source software (MIT License).

Requirements & Download

Hua was written using PowerShell version 5.1 and tested on Windows 10. It should run on any reasonably up-to-date PowerShell installation. An example site (config file, entries file, and content) is included in the distribution so you can try it out immediately.

Hua supports Markdown using the MarkdownToHTML module.

Hua Revision 43 - Sat Dec 10 2022 (Hua.zip, 31K)

Version Notes

• To support Markdown, template substitution values are preceded and terminated by -- instead of ~~. In order to use this version of Hua, all templates must be updated to reflect this.
• Template values --article_tags-- and --master_tags-- need no longer be enclosed in <ul> tags.

Using Hua

Hua is run from the command line by specifying the Hua script and config file. For example: .\hua.ps1 .\hua.cfg.

Config File

The Hua config file specifies the locations of the support files and variables used by Hua (article meta info, output/content/include directories, URLs).

Hua files and config variables:

    entries_file      Delimited text file of blog entries
    content_dir       Directory of the blog content
    output_dir        Directory of the blog output HTML
    index_file        File path of the primary blog page
    archive_file      File path of page listing all article titles
    include_dir       Directory of the various includes
    header_file       File path of header include
    footer_file       File path of footer include
    read_more_file    File name of "Read More..." include
    comments_file     File name of comments include
    blog_root         The web accessible root of the blog
    web_root          The web accessible root of the web site

entries_file  =  .\entries.csv
content_dir   =  .\content
output_dir    =  .\blog
index_file    =  .\blog\index.html
archive_file  =  .\blog\archive.html
include_dir   =  .\content\inc
header_file   =  .\content\inc\header.html
footer_file   =  .\content\inc\footer.html
read_more_file=  .\content\inc\read_more.html
comments_file =  .\content\inc\comments.html
blog_root     =  /blog/
web_root      =  http://example.local

Entries File

The entries file is a comma delimited plain-text database of articles. It can be edited with a text editor or a spreadsheet application (provided the plain-text format is preserved). Each line consists of the following fields:

1. ID: A numeric field. Articles are sorted and presented in descending order using this field.
2. Title: Appears at the top of the article and is linked to the article's permalink.
3. File: The filename of the article's template, stored in the content_dir.
4. Tags: Article-specific tags ("|" delimited). In addition to index and permalink pages, articles appear in the appropriate tag pages.
5. Date: The date presented with the article. Note: This doesn't control the position of the article on the index and tag pages, ID does that.
6. Author: Individual or organization name associated with the article.
7. Contact: Link to individual or organization web page (precede with http://) or email (precede with mailto:) associated with the article.

Errors

Hua is normally silent, so if everything goes well nothing will be output on the command line and Hua will exit with a status of 0. Errors will be output in the following situations:

• No config file is specified. Hua will stop. Exit status of 1.
• The config file can't be found. Hua will stop. Exit status of 1.
• A config variable doesn't exist in the config file. Hua will stop. Exit status of 1.
• The header/footer include doesn't exist. Hua will stop. Exit status of 1.
• The entries file doesn't exist. Hua will stop. Exit status of 1.
• The output directory doesn't exist. Hua will stop. Exit status of 1.
• The read more/comments include doesn't exist. Hua will continue.
• An article content file doesn't exist. Hua will continue to the next article.
• The ID field of an entry in the entries file is empty. Hua will continue to the next article.
• The file field of an entry in the entries file is empty. Hua will continue to the next article.
• A markdown file is referenced in the entries file, but MarkdownToHTML is not installed. Hua will continue to the next article.

Additional Usage Information

• If you want Hua to regenerate an existing article, delete the appropriate article file in the output_dir and run Hua again.
• Pass -o or --orphans as the second argument to list files in the output_dir that are not referenced in the entries_file. If there are no orphans, nothing is output. Content is not processed in this mode.

Known Issues & Future Enhancements

• Master tag list handling.
• Table of contents generation (list of article titles linked to article pages).
• Markdown support.
• Title separator and position variables.
• MarkdownToHTML currently outputs verbose output. This issue has been submitted to the MarkdownToHTML team.

Related Articles

• Integrating Hua's Markdown Support