Thornton 2 dot Com
1K55V

AMTSWG Quick Start Guide (README)

Return to the AMTSWG main page.

Thank you for considering AMTSWG, Ariel Millennium Thornton's Static Website Generator.

AMTSWG is a sort of minimalist Make-based static website generator. You generate and test pages and files on your computer using AMTSWG, then you upload them to a website server that does nothing but serve static pages and static files.

AMTSWG was made for static website authors who do just about everything from the CLI. The only non-CLI programs required are Web browsers, and even then only for website testing.

AMTSWG takes care of the hardest part of maintaining a static website: Keeping your pages looking and feeling like each one is part of a unified coherent website, where every page can be reached and no pages are orphaned or forgotten as your website evolves.

This quick-start guide assumes you want to use the Markdown perl script from Daring Fireball as your lightweight markup language (LML) of choice.

AMTSWG Requirements

Knowledge requirements

You should know how to navigate directories using the Unix or Linux command line, use the shell to manage files and directories, use a text editor, write in Markdown, and make basic websites by writing HTML and CSS files.

Knowing how to use the macro language M4 is a plus, but it's not required.

Required utilities

AMTSWG was developed and tested on FreeBSD 12, but it should work on any Unix, Linux-based, or other reasonably POSIX-like operating system made within the last decade or two.

AMTSWG requires:

Hosting requirements

Your website host needs to let you upload files directly to your website directory on their server, preferably via SSH and rsync.

Your website host doesn't need anything fancier than an HTTP server, whether it's Apache, NginX, Lighttpd, or even thttpd. They don't need Ruby, Python, PHP, Perl, Node, any other CGI, or database support in order for AMTSWG to work.

AMTSWG Deletes Files

AMTSWG deletes files.

AMTSWG deletes files!

AMTSWG deletes files!

AMTSWG assumes you're making a new website, or a website that will replace absolutely every file in your current website. When AMTSWG uploads your website's files, it will by default delete any files already there that it doesn't know about.

AMTSWG does not assume that you're switching from another website framework for an existing website, and it has no capability to import content from any other source or framework.

If you don't want it to delete whatever files are already there on your website host's server, then you must copy them down to your computer, and then save the files in your PUB_DIR directory to let AMTSWG know about them. You'll know which directory on your computer that actually is later on in this file, while installing and configuring AMTSWG.

AMTSWG will not delete files on your website host's server until you do the last step, uploading your new or changed website.

AMTSWG will not delete any files outside the directory you give as the root of your website space on your host's server. If you're using shared hosting and have more than one website hosted there, then AMTSWG will take over only the one website's root directory you name and leave all the others alone.

Even though AMTSWG should not unexpectedly delete anything (and will not if properly configured and bug-free), you should still make backups and test them just in case.

Typing Commands and Text Given in These README Files

You will be asked to type commands to accomplish your goals. Generally speaking, these commands will be shown indented 4 spaces (or in a code block) and with a command prompt (either "$" or ">") to emphasize that they are shell commands. Do not type the command prompts, only the text that follows them.

Some commands will need you to substitute names or values. These are generally shown by enclosing them in angle brackets. Replace them with the text you need, and do not type the angle brackets.

You will be asked to type specific text in your text editor. Like commands, these lines of text will be shown indented 4 spaces or in a code block, but unlike commands, there's no prompt. Type the text given, and do not indent that text. You will also need to substitute text for examples given in angle brackets. Like with commands, replace them with the text you need, and do not type the angle brackets.

Installing AMTSWG

All of the settings are in config.mk, and a fully commented file named config.mk.sample is provided as an example.

The look and feel of your website is controlled by the page template. The file tpl/page.m4 is the default page template. Every page you make is the page body that will be inserted into the template in order to produce complete pages.

Run the following commands, substituting your website's name or address for the example.com directory name and substituting your preferred text editor for the edit command.

  1. Unpack the framework:

    $ pax -rf amtswg-<version>.tar

    (Install tar and use tar -xf amtswg-<version>.tar if your system doesn't have pax installed.)

  2. Name your website framework directory and change into it:

    $ mv -i amtswg <example.com>
$ cd <example.com>

  3. Configure the framework:

    $ cp -ip sitemap.m4.markdown sitemap.m4
$ cp -ip config.mk.sample config.mk
$ edit config.mk

  4. Make your new website:

    $ bin/fixmakefile.sh
$ make new

  5. Configure your website's page template:

    $ cp -ip tpl/page.m4.basic tpl/page.m4
$ edit tpl/page.m4

Using AMTSWG

The current directory must be the root directory of your website framework, where Makefile lives, for AMTSWG to work its magic.

All of the HTML pages that AMTSWG manages for you will live in the src/ directory (unless you changed SRC_DIR in config.mk).

All of the assets your pages need, like images and CSS files, will live in the pub/ directory (unless you changed PUB_DIR). If you want to have HTML pages that AMTSWG won't manage, then they should go in the pub/ directory as well.

Super-quick reference

Creating and Editing Web Pages with AMTSWG

Begin by editing the src/index.txt file. This is your website's home page, or more properly, its source file.

The first thing you should notice is that the file's extension is ".txt" instead of ".html". Every page source file must end in ".txt" for AMTSWG to recognize it.

The next thing you'll notice is that, although src/index.txt has a few M4 macros and some raw HTML in it, virtually all of it is written in Markdown.

Your page source file's header

The part that's neither M4 nor Markdown is the first few lines of the file. These lines give AMTSWG some metadata to plug into your website's page template: the page title, the page author credit, and the date of page authorship. The format of these lines are:

%t <page title, appearing in the title bar and the page heading>
%a <page author, usually you>
%d <today's date, whatever day "today" is when you edit a page>

These lines must be the first lines of the file, no empty lines above them or between them. These lines must be separated from the body of your page by at least one completely empty line. You can put these lines in any order, and you can skip any you don't want to use.

After the first completely empty line, you can put all the Markdown- formatted text you want your page to have.

Quick aside about the date string

Whatever you fill in on the line starting with "%d " will be shown as the page's most recent update date verbatim. That noted, the format does matter in a place or two. Read on, then read "dateformat" for details. The default is "[weekday], [month] [day], [year]".

Linking to other pages made from other source files

When you need to link to other pages on your site, reference those pages as if the src/ directory was the root directory of your website, and with a ".html" (not ".txt") extension. For example, if you create a page file at:

src/computers/commodore/c64.txt

And want to link to it like:

Find out more about the [Commodore 64][1].

Then the link you need to use would be:

[1]: /computers/commodore/c64.html

Embedding images in your page's source file

When you need to embed images in your page, reference those images as if the pub/ directory was the root directory of your website. Unlike with source pages, the file extension doesn't change. For example, if you save an image at:

pub/images/c64desk-1.png

Then the Markdown needed to embed the image would be:

![Typical C64 setup](/images/c64desk-1.png)

Linking to pages, images, and files in your pub/ directory

When you need to link to other files on your website, even HTML files that AMTSWG leaves alone, reference those files as if the pub/ directory was the root directory of your website. For example, if you save a file as:

pub/documents/c64memmap.pdf

And you want to link to it like:

Reference the [Commodore 64 memory map][2].

Then the link you need to use would be:

[2]: /documents/c64memmap.pdf

Testing Your AMTSWG Website

When you're ready to test your website, type the commands:

$ make
$ make test

The "make test" command won't finish. While it's running, open your Web browser and enter the address:

http://127.0.0.1:8080/

Or, if you want to test a specific page:

http://127.0.0.1:8080/<page-file-path-and-name-here>.html

When you're done testing, switch back to the terminal where make test is running, and press Control-C.

Intermediate testing

You can have make test running in one terminal window while editing a page source file in another terminal window, and AMTSWG won't mind.

Every time you make and save a change to a page source file while having its compiled HTML file open in your browser, you must run this command before refreshing the page in your browser:

$ make pages

If you're editing a file in the pub/ directory while testing your site, one of the site's CSS files for example, then every time you save a change, you must run this command instead before refreshing the page it affects:

$ make sync

If you forget, then you won't see the changes you expect to see in your browser.

Advanced testing

You should test your site with as many different Web browsers as you can, especially if you're making modifications to CSS or including JavaScript code.

If you have more than one computer on your LAN, then you can test your website with Web browsers on the other computers. You will need the IP address of the computer running the make test command. You can usually get that by opening a new terminal and running the command:

$ ifconfig | grep inet

or:

$ /sbin/ifconfig | grep inet

One of the lines output should be your IP address. For example:

inet 192.168.0.5 netmask 0xffffff00 broadcast 192.168.0.255

Then on the other computer, open a Web browser and enter the address:

http://<found-ip-address-here>:8080/

Continuing the example above, the address you would enter would be:

http://192.168.0.5:8080/

If one of your other computers runs Microsoft Windows, then this will allow you to test your website in Microsoft Internet Explorer and Microsoft Edge before uploading your website. If you have Apple or Android devices, then this will allow you to test your website in Web browsers on those devices.

Uploading Your AMTSWG Website

Keep in mind that the default RSYNC_OPTS setting in config.mk includes the --delete flag. Any files found in your website directory on your hosting provider's server will be deleted if it isn't also in the stage/ directory (unless you changed DST_DIR) on your computer, so make sure the ADDRESS setting in config.mk is correct before uploading your website.

When your website is ready to upload and serve to the world, upload it with the command:

$ make upload

If you can't use rsync or ssh

You will need to use another program, such as an FTP program, to upload your website. Check your website host's support info.

The only files you need to upload are the contents of the stage/ directory (unless you changed DST_DIR in config.mk).

When you upload your files, keep the directory structure the same between your computer and your host's server, and make sure the first level contents of your website directory on the server are the contents of the stage/ directory on your computer, not the stage/ directory itself.

For example, if your AMTSWG directory on your computer is:

~/projects/example.com/

And the root directory of your website on your host's server is:

~/example.com/

Then you would need to make sure that the files on your computer named:

~/projects/example.com/stage/index.html
~/projects/example.com/stage/computers/commodore/c64.html
~/projects/example.com/stage/documents/c64memmap.pdf
~/projects/example.com/stage/images/c64desk-1.png

Appear on your host's server as:

~/example.com/index.html
~/example.com/computers/commodore/c64.html
~/example.com/documents/c64memmap.pdf
~/example.com/images/c64desk-1.png

If You Forget Anything About Using AMTSWG

Type:

$ make help

That's It

That's basically all there is to it. Enjoy using AMTSWG!

If you want to know more about using AMTSWG, read the README.more and README.robotstxt files next.

~ArielMT