Jeff Rankin Project Miscellany & Blog

Projects / Hua: A PowerShell Static Content Generator

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. The latest Hua distribution is available here (Hua.zip, 95K). An example site (config file, entries file, and content) is included in the distribution so you can try it out immediately.

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
    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
    tags_file         File name of the tag list 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
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
tags_file     =  .\content\inc\tags.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: Individual or organization email 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:

Additional Usage Information

Future & Contributing

Future enhancements include:

Comments, suggestions, or questions about Hua? Let me know!