More Info About AMTSWG (README.more)

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.99.

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:

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 "^$".
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.
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.
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 quick start guide documents page header lines that start with "%t ", "%a ", and "%d ", but there are a fourth and fifth header line that can be used: "%tpl " and "%dep ".

The %tpl header

A header line that starts with "%tpl " (note the space) 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.

The %dep header

A header line that starts with "%dep " (again, note the space) adds a file to the list of dependency files needed to turn the page source into an HTML page. The format is:

%dep <filename> [...]

The filename can be either an absolute pathname, a relative pathname, or a bare filename. You can specify more than one file on a %dep line, and you can specify more than one %dep line. However, you can't split a single filename across multiple source file lines. (See below for more.)

Any files you name are searched for in the following order:

The path as given in the name (if one is given),
The TPL_DIR directory,
The directory the page source file is in,
Each directory between SRC_DIR and the page source file, deepest directory first.

If a file is not found, then a warning is shown when make pages is run, and the file is not included as a dependency.

You would want to use a %dep header line if you want to use M4 to include or paste another file into your page source file, boilerplate text, Markdown, HTML, or macro definitions for example. If you name that included or pasted file as a dependency, then any changes you make to that included/pasted file will trigger rebuilding the page. If you don't, then you would have to touch the page source file yourself after any changes instead.

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

The exception is the "%dep " header line. Since the lines are a list of files, never less than a whole filename per line, spaces are automatically inserted between lines before the list is parsed.

M4 Usage in the Source File

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

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" (without the space) instead of just "dnl". This was done so that you wouldn't invoke a built-in M4 macro by accident while writing pages.
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.
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.
- Remember that the [ character has special meaning to Markdown, so if you need to insert one or a pair as literal text, don't forget to backslash-escape them.
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.

Note: If you edit the file being included into your page source, then that page will NOT be rebuilt unless you declare the included file as a dependency with the "%dep " header line. If you don't add it as a dependency, then you'll have to touch the page source file every time you edit the included file.
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 have a file in SRC_DIR with spaces in the name, the files make target will skip over it, refusing to add it to files.mk, and show a warning message. If you try to force the issue, then make won't understand it, 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:

$ find -L src/ -exec grep -l <old-file-name.ext> {} \;

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:

$ find -L src/ -exec grep -l <old-txt-file-name-sans-ext>.html {} \;

You don't have to include the file extension, but you run the minor 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.

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