[#] Why AutoSite?
So! You're building a static site—writing out good, clean, speedy HTML by hand. Maintaining a static site is much faster and simpler than dealing with a full web stack, but it isn't without its own struggles:
- The average web page features its title in multiple spots on the page, doubly so for any metadata and OpenGraph embedding information you might feature on your site. It's rather easy to forget to update any one of those spots.
- The text on a web page often changes page to page, while the layout information does not. Naturally, the two are always intertwined, even with a stylesheet. At best, you'll be burning out your eyes much quicker staring at a dense wall of tags and text; at worst, retyping things can lead to mistakes and inconsistencies creeping in, something that can spread to many other pages.
- Refactoring that layout? You're likely to be moving around elements in your markup and then porting those changes to other pages—again, a lot of work that can lead to errors and inconsistencies.
- Potentially, your site's files are a mess of HTML documents, supplementary materials for operation (scripts, stylesheets, sitemaps), and random junk for simple viewing and downloading. It can be a real pain finding the page you're working on in that mess, even with a good folder scheme.
- These problems are all compounded the bigger your site is. Imagine fixing something as simple as a broken link on 30 pages, let alone anything bigger! Imagine more!
In short, a static site comes with plenty of its own challenges. Keeping a page chock full of metadata and layout information maintained is enough of a task—juggling an entire site of dense pages on your own can be downright frustrating!
[#] A Summary of AutoSite's Features
AutoSite was built with the express purpose of taking the sting out of maintaining a static site filled with near-identical pages. The theory behind it is that a single, full, rich, dense HTML document can be used as a template, and an infinite amount of much simpler, bare bones input pages containing only what's unique to each one can each be merged into that template. When your site is built by AutoSite, each merge comes out as its own clean, consistent, and error-free page, ready to be uploaded to a web host.
The end result? Fixing bugs means fixing only the template, and it's impossible to forget to update something somewhere when the computer takes care of it for you. Any number of templates can be set up, and each page can be set to use any template you choose.
AutoSite is incredibly flexible and customizable. Aside from page templates, you can set custom attributes on input pages—snippets of text that get merged into the template anywhere you need them to. This helps keep your titles and descriptions consistent. Special attributes enable you to keep your relative paths straight across a complex folder scheme or insert a modified date into your page to let your viewers know when you last updated.
Attributes become even more useful when paired with conditionals, which can be used to alter the layout, look, and functionality of a page depending on the value of a specific attribute. Entire chunks of markup can either be hidden or made to appear with a conditional—useful for making warnings or notices appear on specific pages, applying alternate stylesheets, branching navigation (so links only appear on certain pages), and many, many other potential uses.
AutoSite can be used in one of two ways. The main AutoSite program comes in the form of an IDE that lets you manage files, preview your site, and quickly and easily integrate attributes and conditionals into your markup. AutoSite also comes in a separate, command-line variant called AutoSite Core, which builds in the path it's given as a parameter, or the working directory otherwise. This variant is useful in batch files or in other IDEs for quick and easy project building that skips the GUI's extra features.
[#] How Things Come Together
To drive the point home, let me give a brief example of a template, an input page, and AutoSite's output of the two.
<!DOCTYPE html>
<html lang="en">
<head>
<title>[#title#]</title>
<meta charset="utf-8">
<link rel="stylesheet" href="global.css">
<link rel="stylesheet" href="[#color#].css">
</head>
<body>
<h1>[#title#]</h1>
[#content#]
<footer><p><strong>Last modified:</strong> [#modified#]</p></footer>
</body>
</html>Here's a very basic page template. It features a few special attributes ([#title#], [#modified#]), as well as a custom one, [#color#], for loading in a color-coded stylesheet depending on a value set in the input page.
<!-- attrib title: AutoSite example --> <!-- attrib template: default --> <!-- attrib color: yellow --> <p>Here's a brief example of AutoSite in action. You store only the page's text in the input page (like this one), and AutoSite will merge it automatically into the template.</p>
And here's an input page. You'll have many input pages in an AutoSite project, but potentially only a single template. When AutoSite builds the project, you'll receive an HTML document like this as output:
<!DOCTYPE html>
<html lang="en">
<head>
<title>AutoSite example</title>
<meta charset="utf-8">
<link rel="stylesheet" href="global.css">
<link rel="stylesheet" href="yellow.css">
</head>
<body>
<h1>AutoSite example</h1>
<p>Here's a brief example of AutoSite in action. You store only the page's text in the input page (like this one), and AutoSite will merge it automatically into the template.</p>
<footer><p><strong>Last modified:</strong> 11/23/2020</p></footer>
</body>
</html>Writing pages using AutoSite is quite the same as how you write pages already—just that instead of writing the entire page every time, you only write the layout once, and then the meat of the page separately. AutoSite does the rest.
Hopefully, you're beginning to see just what good AutoSite does for the right kind of site, and hopefully, this manual will provide enough documentation to get you started.
[#] Making a New Project
To start a new project, in the GUI, pull down the File menu and select "New Site...". AutoSite will prompt you where you'd like to save the new project. (If a project already exists in that folder, AutoSite will simply load it, so pick a new, clean folder.)
After you've picked a place and your project is generated, AutoSite will pop up its Quickstart dialog. This gives you a set of simple tasks you can use to get your first project up and running. You can access the Quickstart dialog at any time in Tools > "Quickstart".
