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 third-party engine like Disqus or IntenseDebate. Hua is open source software (MIT License).

Requirements & Download

Hua has been tested on Windows 10 and Ubuntu 22.04. It should run on any reasonably up-to-date PowerShell installation. An example site (config file, entries file, meta info file, and content) is included in the distribution so you can try it out immediately.

Hua supports Markdown using the MarkdownToHTML module.

Hua Revision 153 - Wed Jul 3 2024 (Hua.zip, 47K)

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
    meta_file         Delimited text file containing blog meta info
    content_dir       Directory of the blog content
    markdown_dir      Directory containing the markdown template
    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
    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
    title_sep         Character(s) used to separate elements in the title
    entries_pp        Number of entries per page (for paging)
    next_label        Label of next page link (replace spaces with  )
    prev_label        Label of previous page link (replace spaces with  )
    log_dir           Directory in which log file (hua.log) is output

entries_file   =  .\entries.csv
meta_file      =  .\meta.csv
content_dir    =  .\content
markdown_dir   =  .\markdown
output_dir     =  .\blog
index_file     =  index.html
archive_file   =  archive.html
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
title_sep      =  /
entries_pp     =  2
next_label     =  Next Page
prev_label     =  Previous Page
log_dir        =  .

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.

Meta File

Article meta information is stored in a separate, pipe-delimited file. Like the entries file, 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. Must correspond to the appropriate article in the entries file.
  2. Keywords: A comma-delimited list of subject keywords appropriate to the article.
  3. Description: A description of 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

Known Issues & Future Enhancements

Related Articles