AMTSWG: Ariel Millennium Thornton's Static Website Generator ============================================================ AMTSWG is a Make-based static website generator. A static website generator is a set of tools that lets you compose, edit, and upload Web pages to your website from your PC relatively easily, but without running any applications or extra code on your website's server. All you need for a static website is an HTTP server, such as Apache, Nginx, or thttpd on the server and a shell, text editor, and Web browser on your PC. A Make-based generator uses the "make" tool built in to most distributions of Unix and Linux to turn source pages into ready-to-upload HTML pages with consistent layout and themes. AMTSWG expands on these by letting you compose source text in a combination of M4 macros (which you don't have to use) and one of a small selection of lightweight markup languages (LMLs), such as Markdown (the default), reStructuredText, or txt2tags, instead of raw and wordy HTML. AMTSWG is best used from the shell or a terminal window with a CLI text editor like EMACS, Vim, Nano, or ed. As such, it's perfect for website authors who do just about everything from the CLI. The only non-CLI program required is a Web browser or two for testing purposes. (CLI browsers like Lynx and Links are not recommended without a GUI browser as well for complete testing.) AMTSWG Requirements ------------------- ### Knowledge requirements You should know how to navigate the Unix or Linux command line, use commands, and use a text editor. You should know how to make basic websites by writing HTML and CSS files. If you want to use a supported LML, you should know how to make basic websites by writing files in your chosen LML and transforming the LML files into corresponding HTML files. Knowledge of M4 is entirely optional. You do not need to know how to use M4, but you can if you do know. ### Basic Unix utilities AMTSWG was written for POSIX compliance. The computer you use AMTSWG on should run a POSIX-compliant OS. If your OS uses GNU utilities (such as the most popular Linux distributions), check that they have POSIX- compliant modes and command line switches; almost all do, but make sure. The following commands are required. Most are provided by coreutils and installed by default, but some like m4 may be in separate, optional packages for your OS. * make, m4, [, basename, cat, comm, dirname, find, grep, mktemp, sed, sort, tar, tr, which ### Lightweight markup language (LML) to HTML translator One of markdown, rst2html, txt2tags, or pandoc. By default, markdown is the required LML command. If you want to use another LML (or no LML and write straight HTML), then read and edit "config.mk" for your desired LML and install the corresponding LML commands. ### Optional requirements In order for the "make test" Make command to work, you must have Python installed. Most Unix and Linux distributions install the Python command as "python", but some distributions (such as FreeBSD) install the Python command as "python2.7" or "python3.6" instead. If the latter case is what your OS does, then edit "config.mk" for your actual Python command. In order to use the _pygmentize() M4 macro in "tpl/pygment.m4" for source code syntax highlighting, you must have Pygments installed. Installing AMTSWG ----------------- Unpack AMTSWG into the directory where you want your new static website to live, and rename the "amtswg" directory to your website's name. CD into your AMTSWG directory. Edit the file "config.mk" and change its settings to match your website and server settings. Run this Make command: * make new Edit the file "tpl/page.m4" (unless you changed TPL_DIR in "config.mk") and change its settings to match your website. Upgrading AMTSWG ---------------- No real upgrade path is provided because this project is not expected to see frequent updates. Before beginning, make a backup copy of your AMTSWG website directory, test that backup copy, and read the README for the new AMTSWG. If its directions are not the same as this file, follow the new one instead. First, make sure that no directory called "amtswg" curently exists. Then, unpack the new AMTSWG. CD into the "amtswg" directory, and run this Make command: * make new Run the following commands, substituting the names in brackets with your actual website directory names. For example, if your AMTSWG website is in "~/example.com", then you would replace "/bin/" with "~/example.com/bin/". 1. cp LICENSE / 2. cp Makefile / 3. cp README / 4. cp config.mk.sample / 5. cp files.mk.if-make-aborts / 6. cp sitemap.m4.* / 7. cp bin/* /bin/ CD into your AMTSWG website directory. Compare the new config.mk.sample file with your config.mk file, and make sure the options are still set the way you want and expect. Compare the relevant new sitemap.m4.* file with your sitemap.m4 file, and make any necessary changes. Run this Make command to make sure AMTSWG still understands your website: * make check If anything goes wrong, restore your AMTSWG website directory from your backup copy. AMTSWG Directory Structure -------------------------- ### Simple structure amtswg/ | +-- Makefile -- The heart of AMTSWG | +-- $PUB_DIR/ - (pub/ by default) | | | +-- Every static file resource you want in your website. Create | | subdirectories here to organize your files. | | | +-- css/ -- Directory recommended for storing CSS themes and | | files. | | | \-- images/ -- Directory recommended for storing images. | +-- $SRC_DIR/ - (src/ by default) | | | +-- Any *.txt files here are compiled into HTML files. Any | | files NOT ending in ".txt" are left alone. | | | +-- index.txt -- Compiles into index.html, the default page for | | your website. | | | \--sitemap/ | | | \-- index.txt -- Automatically generated by "make sitemap" | \-- * -- See the complete structure for other directories and files. ### Complete structure amtswg/ | +-- LICENSE --- The FreeBSD 2-Clause license for AMTSWG | +-- Makefile -- The heart of AMTSWG | +-- README ---- This file | +-- config.mk - AMTSWG configuration for Makefile | +-- config.mk.sample - Example AMTSWG configuration | +-- files.mk -- Automatically generated by "make files". No need to | edit or change manually. | +-- files.mk.if-make-aborts -- If Make aborts because files.mk is | corrupted or missing, run the command | "cp files.mk.if-make-aborts files.mk" | and re-run "make files". | +-- sitemap.m4 -- M4 macros for generating the Site Map page. By | default, in the LML Markdown. | +-- sitemap.m4.* -- Same as sitemap.m4, but with defaults for | generating the Site Map page in other LMLs. | +-- bin/ ------ Shellscripts automating much of Makefile. Do not edit | except to fix bugs. | +-- $PUB_DIR/ - (pub/ by default) | | | \-- Every static file resource you want in your website. Create | subdirectories here to organize your files. This directory | is copied to the root of your website unmodified and with | your subdirectory structure intact. | Replace favicon.ico, add images to favicon/, and change | tpl/page.m4 if you don't want to use the default packing box | image for your website's favicon. | +-- $SRC_DIR/ - (src/ by default) | | | +-- Any *.txt files here are compiled to $DST_DIR/*.html files. | | Any files whose names DO NOT end in ".txt" are left alone, | | neither compiled nor copied anywhere. | | Examples: | | | +-- index.txt -- Compiles into index.html, the default page for | | your website. The default contains examples | | specific for Markdown. | | | +-- about.txt -- Does not exist by default. Create it, and it | | will compile to about.html, enabling the | | "About" link in the page template to work. | | | \-- sitemap/ | | | \-- index.txt -- Generated automatically by "make | sitemap". You don't need to create or | edit this file. | +-- $DST_DIR/ - (stage/ by default) | | | \-- Every compiled file from $SRC_DIR/ is staged here once | into an HTML page, and every file from $PUB_DIR/ is staged | staged here by "make sync". DO NOT add or delete any files | in this directory; Make will take care of keeping it in | sync with your source files. | +-- $TMP_DIR/ - (temp/ by default) | | | \-- While compiling and syncing, temporary files are put here. | Do not use this directory for any kind of storage. While | Make is not running, you can delete any stray files and | directories that weren't cleaned up if you want to. | \-- $TPL_DIR/ - (tpl/ by default) | +-- Templates and helper M4 macros. | +-- page.m4 -- The main site page template. Edit this file to | make your AMTSWG website yours. | +-- page.m4.* -- Alternate-theme page templates. | "page.m4.basic" is the default. To use an | alternate template, edit the alternate template | file just like "page.m4", then copy it to | "page.m4". | +-- htmlhelpers.m4 -- Helper M4 macros to let you more easily | use HTML features that your LML doesn't | support. Include the line: | "m4_include([[htmlhelpers.m4]])m4_dnl" | in your page source file to make them | available. Read this file for more info. | \-- pygment.m4 -- Comtains the "_pygmentize" macro so you can include syntax-highlighted source code snippets in your pages. Note that this will significantly slow down page compilation. Include the line: "m4_include([[pygment.m4]])m4_dnl" in your page source to make the macro available. Read this file for more info. Using AMTSWG ------------ It's a good idea to have a shell or terminal window open whenever you're working on your AMTSWG site, with the current directory set to your AMTSWG directory. You must be in this directory in order for Make to recognize your commands. If you forget which Make command to run, run this Make command for a brief summary: * make help ### New files You will save files in two directories: * The PUB_DIR directory (pub/ by default), which contains ready-to-upload files like CSS files, JavaScript files if your site uses any, and image files. * The SRC_DIR directory (src/ by default), which contains LML files (or M4/LML files) that will be turned into HTML pages. No matter which LML you use, your file names must end in ".txt", or they won't be recognized. For example, "somefile.txt" will become "somefile.html", but "somefile.txt.bak" will be ignored. Before being uploaded to your website server, all of the files will be compiled and assembled into a third directory: * The DST_DIR directory (stage/ by default). Never save anything here yourself, because AMTSWG will delete everything here that it thinks doesn't belong. ### New webpages If you want to create a page that will be accessed via the URL "http://example.com/my-new-webpage.html" (example.com being a stand-in for your website's root), then create your page content in LML format and save it as "my-new-webpage.txt" in SRC_DIR. When it's ready, run either of these two Make commands to compile it to a ready HTML page: * make $DST_DIR/my-new-webpage.html * make pages The structure of a page is a header, a blank line, and then your page content: > %t > %a > %d > > Your page content here. The "%t", "%a", and "%d" items in the header lines can appear in any order, and any of them can be omitted, but they must all be clustered into one group of neighboring lines at the very top of the file. The percent sign ("%") must be the first character of each line. If you specify any of the three items more than once, each like item will be combined into one. The line after these header lines must be an actual blank line. There can't even be a blank space or tab on the line. You can have as many blank lines as you want. All the text after the first blank line will be treated as your page text written in your LML. ### New static files and images If you want to add images, a file named "my-image.jpg" for example, save it in PUB_DIR, and embed it in your webpage as "/my-image.jpg". When uploaded to your website server, files in PUB_DIR will be copied to the root directory of your website. This means "$PUB_DIR/my-image.jpg" on your computer will be "/my-image.jpg" on your website, and "$PUB_DIR/images/my-image.jpg" on your computer will be "/images/my-image.jpg" on your website. After adding, changing, or removing files in PUB_DIR, run this Make command: * make sync ### Renaming or relocating Web pages If you want to rename a page in SRC_DIR or move it to a new directory under SRC_DIR, then actually move or rename the file, and run all of these Make commands: 1. make sync 2. make sitemap 3. make files 4. make pages ### Deleting Web pages, files, or images If you want to outright delete a page in SRC_DIR, permanently removing the corresponding HTML page from your website, then actually delete the file in SRC_DIR, and run all of these Make commands: 1. make sync 2. make sitemap 3. make files 4. make pages If you want to outright delete a file or image in PUB_DIR, permanently removing the file from your website, then actually delete the file in PUB_DIR, and run this Make command: * make sync Testing Your AMTSWG Site and Pages ---------------------------------- Always proofread and test your website whenever you make changes so that you can fix errors and typos without them going live on your website server. To test your website, after you run all the other necessary Make commands, run this Make command: * make test This Make command will run indefinitely, and the only way to stop it is to press CTRL+C while your terminal has focus. While this Make command is running, open or switch to your Web browser, and go to the URL "http://127.0.0.1:8080/" to access your website. Browse around in it and make sure there aren't any typo, grammar, or layout errors. If there are, edit the appropriate files, run the Make commands again, and reload the page. When editing files while "make test" is running, DON'T FORGET to run the right Make commands between saving your changes and reloading the Web page. Uploading Your Ready AMTSWG Site to Your Server ----------------------------------------------- When you're ready to upload your website to your server and let the world access it, run this Make command: * make upload WARNING: By default, the rsync options mean that any file not in the DST_DIR directory on your computer WILL BE DELETED from your website's server space. This is to ensure that the only files you serve are the files you mean to. Once the upload finishes, your actual website is up to date. Customizing Your AMTSWG Website ------------------------------- There are various page templates in the tpl/ directory named "page.m4.theme-name" (where "theme-name" is the page theme). The file "tpl/page.m4" is the template file for your website. By default, it's a copy of "tpl/page.m4.basic". If you're going to use any of the alternative page templates, then first edit and customize them for your website, then copy the alternative file to "tpl/page.m4", and next run this Make command: * make pages If "make pages" doesn't regenerate any pages or only rebuilds the site map page, it may be because the Make system looked at the timestamp of the overwritten "tpl/page.m4" file and decided it's not newer than the generated HTML pages. Run these commands if this is the case: 1. touch tpl/page.m4 2. make pages Finally, test your website with the different theme as described in "Testing Your AMTSWG Site and Pages" above. If you're reasonably skilled in HTML and CSS, you can create your own "tpl/page.m4" and corresponding CSS files to create your own website theme and template. You should save your CSS file as "PUB_DIR/css/filename.css" and link it in as "/css/filename.css", but this is only a suggestion. The only hard requirement is that you save any external CSS in a file or directory under PUB_DIR. Using M4 in Your LML Page Source Files -------------------------------------- You don't have to use any M4 macros in your LML source files, but the example "SRC_DIR/index.txt" file shows some of them in use along with comments about how to use them. AMTSWG processes SRC_DIR files with M4 before processing them with your LML converter, so if you write any M4 macros, make sure they output valid LML, not HTML. (Markdown is an exception: It leaves any HTML blocks it finds alone, so it's okay to have M4 macros produce HTML if your LML is Markdown.) AMTSWG makes some changes to M4 defaults in order to prevent them from being invoked and causing errors or strange behavior by accident: * All M4 macros begin with the text "m4_". For example, the "define" command described in the M4 manpage has to be used as "m4_define" instead. This was done to prevent accidentally using M4 commands when you write LML without M4. * The octothorpe character ("#") is used in LMLs like Markdown as a header marker, but it's used in M4 as a comment character, which probably isn't what you expect. In AMTSWG, the comment character is disabled so this won't happen. The only way to embed comments that won't appear in your HTML pages is with the "m4_dnl" macro. * In default M4, the backtick and single-quote characters ("`" and "'") are used to begin and end quotes. If AMTSWG let this stand, then things like Markdown code blocks and ordinary contractions wouldn't be possible. In AMTSWG, the quote characters are changed to pairs of opening and closing brackets ("[[" and "]]") instead, character sequences much less likely to be used accidentally. The example SRC_DIR/index.txt file shows this in action. Administrivia ------------- AMTSWG was created by Ariel Millennium Thornton. AMTSWG is copyright 2019 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 .