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.
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.
AMTSWG was developed and tested on FreeBSD 12, but it should work on any Unix or Linux-based operating system made within the last decade or two.
- All the basic Unix/Linux commands
- M4 macros are used throughout the framework
- The heart of AMTSWG
- The LML you'll write pages in
- Syntax highlighting for code blocks in your pages
- Website testing
- Website uploading
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 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, after 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.
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 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, 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.
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. 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.
Unpack the framework:
$ tar -xzf amtswg-0.3.1k489.tar.gz $ mv amtswg example.com $ cd example.com
Configure the framework:
$ cp sitemap.m4.markdown sitemap.m4 $ cp config.mk.sample config.mk $ edit config.mk
Make your new website (ignore the "mkdtemp" error):
$ bin/fixmakefile.sh $ make new
Configure your website's page template:
$ cp tpl/page.m4.basic tpl/page.m4 $ edit tpl/page.m4
The current directory must be the root directory of your website, 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.
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.
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:
And want to link to it like:
Find out more about the [Commodore 64].
Then the link you need to use would be:
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:
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:
And you want to link to it like:
Reference the [Commodore 64 memory map].
Then the link you need to use would be:
Testing Your AMTSWG Website
When you're ready to test your website, type the commands:
$ make files $ make $ make test
The "make test" command won't finish. While it's running, open your Web browser and enter the address:
Or, if you want to test a specific page:
When you're done testing, switch back to the terminal where "make test" is running, and press Control-C.
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.
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
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:
Continuing the example above, the address you would enter would be:
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:
And the root directory of your website on your host's server is:
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
$ make help
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.