By William Jeffrey Rankin, Sat Nov 29 2025
Have you just downloaded Hua and are wondering how to get started? Here's how you can create your first article!
First, copy and paste the code of this minimal article into a file named hua-first.md. Put the file in Hua's content directory.
Next, open entries.csv in Hua's root directory in a text editor and add this line at the end of the file:
000050,My First Article!,hua-first.md,tag|another,11/29/2025,Author Name,mailto:someone@email.com
Now open meta.csv and add this line (this step is optional, by the way):
000050|tag, article, Hua|This is my first article!
You're nearly there! Open a command shell or terminal, navigate to your Hua directory, and type the following:
pwsh hua.ps1 example.cfg
The output will look something like this. Don't worry about the errors (unless it mentions your article specificially) — these are present to demonstrate Hua's error handling.
Content file error. File (ID: 000047) is empty. Skipping.
Content file error. File (ID: 000045) is empty. Skipping.
Entries file error. There is an entry (ID: 000040) without a filename. Skipping.
Entry content error. Entry content file path set as .\content\missing-2.md. Skipping.
Entry content error. Entry content file path set as .\content\missing-1.html. Skipping.
Related article error in 000020. Article ID 000017 does not exist. Ignoring.
Entries file error. There is an entry without an ID. Skipping.
Finally, open the blog directory. It will contain the newly generated file, hua-first.html. The article will also appear in index.html, the tagged with files, and archive.html. That's it!
By William Jeffrey Rankin, Sun Aug 3 2025
Revision 294 of Hua supports automatic generation of related articles. Simply append one or more IDs to the appropriate article in the entries file. Here's an example from this blog:
00165,planet-rs Improvements,prs-improvements.md,development|astronomy,Sat Jul 26 2025,William Jeffrey Rankin,mailto:jeffrey.rankin@me.com,00031|00032|00090
Articles are listed in the same order they appear in the entry. Hua will display (and log) a warning should the related article ID not exist in the entries file:
Related article error in 000020. Article ID 000017 does not exist. Ignoring.
By William Jeffrey Rankin, Thu Feb 13 2025
Hua has an "orphans" mode that enables the identification of files that exist in the output directory but not in the entries file. Here's an example using the sample content files:
$ pwsh hua.ps1 example.cfg -O
orphan-1.html
As there may be perfectly valid reasons for the file to exist (e.g., a file referenced in generated content like a PDF or a download) Hua takes no action beyond listing the orphan filename.
It occurred to me this mode could also be used to look for orphans in the content directory. All that's required is to change the output_dir variable value in the Hua config file to the location of the content directory. In the example.cfg file change this:
...
output_dir = .\blog
...
to this:
...
output_dir = .\content
...
and run Hua in the same way as above. Content is not processed in orphans mode. Don't forget to change output_dir to its prior value!
By William Jeffrey Rankin, Mon Dec 30 2024
A Hua tar archive is now available for Linux hosts. It is designed to be installed in /usr/local. An executable shell script is included (hua) as well as a man page.
Like the zip version, it includes a sample web site. To try it out, run the following:
$ mkdir temp
$ cd temp
$ cp /usr/local/share/hua/example.cfg .
$ cp -r /usr/local/share/hua/content .
$ mkdir blog
$ hua example.cfg
The installation looks like this:
\---usr
\---local
+---bin
| hua
| hua-paging.ps1
| hua.ps1
|
\---share
+---hua
| | entries.csv
| | example.cfg
| | Hua.pdf
| | meta.csv
| | MIT-License.txt
| |
| +---content
| | | another.html
| | | first.html
| | | latest.html
| | | markdown-2.md
| | | markdown.md
| | | new-article.md
| | | new-tag.md
| | | no-content.html
| | |
| | \---inc
| | comments.html
| | footer.html
| | header.html
| | read_more.html
| |
| \---markdown
| md-template.html
|
\---man
\---man1
hua.1
By William Jeffrey Rankin, Thu Dec 5 2024
Hua can be run at regular intervals using a scheduled task (on Windows) or a cron job (on Linux/Cygwin). On Windows, I use a simple batch script:
D:
cd Documents\Hua
D:\PowerShell-7.4.6-win-x64\pwsh .\hua.ps1 .\hua.cfg
Then I create a scheduled task. Two examples are shown below: the first runs daily, the second every hour.
schtasks /create /sc daily /st 23:50 /tn "Hua" /tr D:\Documents\Hua.bat
schtasks /create /sc hourly /st 08:05 /tn "Hua" /tr D:\Documents\Hua.bat
On Linux and Cygwin it's a little simpler since the batch script is not necessary. The equivalent cron jobs look like this:
50 23 * * * cd Hua; pwsh hua.ps1 hua.cfg
5 * * * * cd Hua; pwsh hua.ps1 hua.cfg
Note that in the case of Cygwin, you'll need to use the full path to pwsh:
50 23 * * * cd Hua; /cygdrive/c/PowerShell-7.4.6-win-x64/pwsh ./hua.ps1 ./hua.cfg
If you want to suppress Hua's output, direct it to /dev/null as shown below. Output is still sent to Hua's log file.
50 23 * * * cd Hua; pwsh hua.ps1 hua.cfg > /dev/null