Thornton 2 Library of Scraps
1K489

More Info About AMTSWG (README.more)

Return to the AMTSWG main page.

Read the README file first.

These are useful things to know about Ariel Millennium Thornton's Static Website Generator (AMTSWG) that aren't in the quick start guide.

Reminder About URLs That Don't End in a Filename Suffix

In AMTSWG, every generated page ends in ".html", which means that every URL to a page file also has to end in ".html".

The only way you can get around this limitation and use a URL to a generated page that doesn't end in ".html" is to make the URL a directory name.

For this to work, the page source file in that directory must be named "index.txt", and this will generate the default page Web servers serve when given just a directory URL, "index.html".

If you forget to do this, then the Web server will either serve a context-less listing of the directory's files or serve an error page.

The Site Maps, the Exceptions To Manual Source Page Editing

The AMTSWG Makefile has a target named sitemap, and it creates and fills in a pair of site map files for you, relieving you of the burden of keeping track of which pages you have or don't have on your website.

One of the site map files lives in "SRC_DIR/sitemap/index.txt". This file is the lone exception to editing source pages manually. AMTSWG itself updates this file whenever you run "make" or "make sitemap", but if you insist on editing it yourself, AMTSWG also makes a backup of it before writing a new one. The backups are numbered, named from "index.txt.0" through "index.txt.999".

The generated site map file SRC_DIR/sitemap/index.txt allows you to point visitors to your site map page with the URL "/sitemap", where they'll see every page title sorted alphabetically by URL. They will not see any URLs whose files are in PUB_DIR. (See "Secret pages" below for any pages in SRC_DIR you don't want in your site map files.)

The generated site map file PUB_DIR/sitemap.txt is a plain listing of fully qualified page URLs conforming to the sitemaps.org description for plain text files at:

https://www.sitemaps.org/protocol.html#otherformats

You can submit the generated and uploaded sitemap.txt file to search engines to inform them that their spiders should crawl and index your site, and you can reference it from your robots.txt file for the same purpose.

Secret pages

AMTSWG allows you to have "secret" pages on your website. These pages will be fully accessible to the Internet at large without any extra form of access control, just like all the normal pages on your website, and it's possible search engines will still find them if anyone links to them, but they will never appear in either of your site map files.

All you have to do is make your page a hidden file or save the page in a hidden directory. Hidden files and directories are files and directories whose names start with a period or dot character.

Apache and .htaccess

If your Web server uses Apache and you want to have a .htaccess file and/or .htpasswd file in your website, remember to put it in PUB_DIR, not in SRC_DIR.

If you decide to use .htpasswd password protection, remember that any passwords sent and checked against .htpasswd are encoded, not encrypted, and the difference has critical security implications. Don't use one without making your hosted website use SSL or TLS encryption as well.

How Pages Are Built

Pages are built from source files in four steps:

  1. The header metadata is separated from the source file and parsed for later use in the page template. The separator is a completely empty line made by two consecutive newline characters. The regular expression used by sed in finding this separator line is "^$".

  2. The rest of the source file is passed through M4. Any M4 macros found are processed, and the results are expected to be HTML and/or LML text.

  3. The processed source file is passed through the LML processor and translated into an HTML fragment. The result must not be a complete HTML page at this step.

  4. The page template is passed through M4, together with the parsed metadata from step 1 and the HTML fragment from step 3. The result is the finished page, which is saved into the DST_DIR directory ("stage/" by default).

Page Header Metadata

The %tpl header

The quick start guide documents page header lines that start with "%t ", "%a ", and "%d ", but there is a fourth header line that can be used: "%tpl ".

A header line that starts with "%tpl " overrides the page template used for building the final page. The format is:

%tpl <page-template-file-name>

The file has to exist in TPL_DIR ("tpl/" by default), and it's used instead of TPL_DIR/page.m4 when building the page.

This allows you to have different page designs for different purposes, for example subtly different pages for site sections, each of which contains additional links specifically for that section.

If you use "%tpl ", then the file you reference must be an M4 file.

Headers folded from multiple lines

In addition, you can specify "%t ", "%a ", and "%d " lines more than once. If you do, then all the lines of the same type will be grouped together, and their content will be folded into a single line. In this way, you can take page titles and author credits too long for a single text editor line and split them up across multiple text editor lines.

If you specify a header line more than once, add an extra leading space between the header letter ("%t " for example) and the first word of the continued line. For example:

%t A Reevaluation of the Stanley Kubrick Classic "Dr.
%t  Strangelove, or How I Learned To Stop Worrying and Love
%t  the Bomb"

This example will be folded into a single line of title metadata with a space preserved between the words "Dr." and "Strangelove" and between "Love" and "the":

A Reevaluation of the Stanley Kubrick Classic "Dr. Strangelove, or
How I learned To Stop Worrying and Love the Bomb

Without that extra space, the lines will be folded together with no space. For example:

%t The
%t  Meaning
%t  Of
%t  Super
%t cali
%t fragi
%t listic
%t  Expi
%t ali
%t docious

Will be folded into:

The Meaning Of Supercalifragilistic Expialidocious

M4 Usage in the Source File

The M4 environment in the source file is customized in the following ways:

  1. One of the switches used when invoking m4 is "-P", which prefixes all built-in macros with "m4_". For example, instead of defining new macros with "define", new macros must be defined with "m4_define". Additionally, comments in M4 must start with "m4_dnl" instead of just "dnl". This was done so that you wouldn't invoke a built-in M4 macro by accident while writing pages.

  2. By default, actual comments in M4 start with a hash sign ("#") and end with a newline. This default behavior has been turned off so that lines starting with hash signs can be processed by Markdown and other LMLs as not-comment things.

  3. By default, M4 treats the backtick character ("`") as starting a quote and an apostrophe ("'") as closing a quote. This default behavior makes using apostrophes in contractions and possessive adjectives impossible. To get around this, the starting quote has been changed to a pair of open square brackets ("[["), and the closing quote has been changed to a pair of close square brackets ("]]"). This leaves you free to use apostrophes in words without worry.

  4. You can include other files into the source file using the M4 macros "m4_include" and "m4_sinclude". You can do this to reuse text or include custom defined macros, such as the "htmlhelpers.m4" file included with AMTSWG. If the file to include isn't found as-is in the "m4_include" argument, then directories are searched in the following order:

    a. The TPL_DIR directory ("tpl/" by default),

    b. The SRC_DIR directory ("src/" by default),

    c. The directory the source file is in, and

    d. Each parent directory in order between the source file and the SRC_DIR directory.

  5. Because AMTSWG ignores any files in SRC_DIR not ending in ".txt", you can save M4-included text and macros in files ending with any other extension, and they won't be uploaded to your website. That noted, files ending in ".m4" is recommended for M4.

Spaces in Filenames

Any files saved in PUB_DIR ("pub/" by default) are allowed to have spaces in their filenames, but this is not recommended. If you do add such a file, then you will have to embed it or link to it substituting "%20" in place of each space in the name when writing the URL to it.

However, files in SRC_DIR ("src/" by default) and TPL_DIR ("tpl/" by default) ABSOLUTELY POSITIVELY MUST NOT have any spaces in their filenames!

The reason is that spaces are always treated as separators in Makefile targets and prerequisites. There is no way to embed spaces, there is no way to override this behavior in a portable and mostly POSIX-compliant way, and it is extremely difficult at best to override it in a way GNU Make will be okay with.

In the Makefile, spaces are always filename separators now and forever.

If you try to have a file with a space in the name, then "make" won't understand files.mk, and AMTSWG won't be able to update your website.

When files.mk Is Corrupted/Missing and Breaks AMTSWG

Whenever AMTSWG breaks because "make" can't understand targets or prerequisites in files.mk, or because "make" can't find files.mk, run the following command:

$ bin/fixmakefile.sh

Moving and Renaming Files

AMTSWG is not smart enough to fix or detect references to moved or renamed files. Unfortunately, you have to find and fix references to a file yourself whenever you move or rename it.

If you move or rename a file under PUB_DIR ("pub/" by default), then you should finish by using the following command:

$ make sync

If you move or rename a file under SRC_DIR ("src/" by default), then you should finish by using the following commands:

$ make files
$ make pages
$ make sync

In between moving/renaming the file and running "make", you should find and fix references to the old file's name and/or location.

If the file you moved/renamed is in PUB_DIR, then using the following command (substituting the actual value of SRC_DIR for "src/") should list the page source files you need to update:

$ grep -lr <old-name-of-file.ext> src/

If the file you moved/renamed is in SRC_DIR, then using the following command (substituting the actual value of SRC_DIR for "src/") should list the page source files you need to update:

$ grep -lr <old-name-of-txt-file-without-extension>.html src/

You don't have to include the file extension, but you run the risk of listing a file you don't actually need to update if the name is a word you use a lot.

Other Website Themes

The quick start guide walked you through installing and customizing the "basic" theme by copying "tpl/page.m4.basic" to "tpl/page.m4". There are two other themes you can try: "parchment" and "timemachine".

You can use any of these three themes as a base for your own, or you can create a new theme from scratch. Sorry, but there's no theme maker, and the only real documentation are the page template and relevant CSS files themselves.

If you stick with the "basic" theme as-is, then you should create your own site logo, make it roughly the same dimensions as "pub/css/basic/box-clipart-png-sm.png", save it as a PNG image (or other Web-safe format image) anywhere you want in "pub/", and edit the "pub/css/basic.css" file to use that image instead.

Whichever theme you end up using, you should create and install your own favicon images in "pub/favicon/", and edit your "tpl/page.m4" template file(s) to use your favicon images instead.

Administrivia

AMTSWG was created by Ariel Millennium Thornton.

AMTSWG is copyright 2020 by Ariel Millennium Thornton and licensed to you under the terms of the FreeBSD 2-Clause license. See the file LICENSE for details.

Please report any serious bugs to <arielmt(at)thornton2.com>.