Alternator

Getting Started

~/website % alternator --help
USAGE: alternator <source> <target> [--port <port>]

ARGUMENTS:
  <source>                Path to your source directory.
  <target>                Path to your target directory.

OPTIONS:
  -p, --port <port>       Port for the localhost server.
  --version               Show the version.
  -h, --help              Show help information.

The alternator command builds your <source> files into <target>:

~/website % alternator path/to/source path/to/target

Add a --port to make <target> available on localhost:

~/website %  alternator path/to/source path/to/target --port 8080
[watch] watching path/to/source for changes
[serve] serving path/to/target on http://localhost:8080
^c to stop

Pro Tips

<source> changes auto-build while the server is running.
Files whose names start with ! will not be written to <target>.
Markdown files are automatically converted to HTML files:
path/to/source/index.md → path/to/target/index.html
Layouts, includes, variables, and metadata work in:
.css, .htm, .html, .js, .md, .rss, .svg, .txt, and .xml.
All other file types are copied unchanged to <target>.
Dotfiles are completely ignored.

Layouts

Specify a layout with the #layout metadata key.

Any file with a #content comment can be used as a layout.

Source path/to/source/index.html

---
#layout: !layout.html
---
<h1>Welcome</h1>
<p>Hello, world!</p>

Layout path/to/source/!layout.html

<!DOCTYPE html>
<html>
  <head>
    <title>Alternator</title>
  </head>
  <body>
    <!-- #content -->
  </body>
</html>

Rendered path/to/target/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Alternator</title>
  </head>
  <body>
    <h1>Welcome</h1>
    <p>Hello, world!</p>
  </body>
</html>

Pro Tips

#layout and #include paths are relative to <source>.

Includes

Use an #include comment to include another file.

Source path/to/source/index.html

---
#layout: !layout.html
---
<!-- #include !header.html -->
<p>Hello, world!</p>

Include path/to/source/!header.html

<h1>Welcome</h1>

Layout path/to/source/!layout.html

<!DOCTYPE html>
<html>
  <head>
    <title>Alternator</title>
  </head>
  <body>
    <!-- #content -->
  </body>
</html>

Rendered path/to/target/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Alternator</title>
  </head>
  <body>
    <h1>Welcome</h1>
    <p>Hello, world!</p>
  </body>
</html>

Pro Tips

Included files can have their own layouts.
#include arguments override the included file's metadata:

Variables

Define variables with @ symbols and render them in comments.

Assign values in metatdata or as #include arguments.

Source path/to/source/index.html

---
#layout: !layout.html
@siteTitle: Alternator
---
<!-- #include !header.html @pageTitle: Welcome -->
<p>Hello, world!</p>

Include path/to/source/!header.html

<h1><!-- @pageTitle --></h1>

Layout path/to/source/!layout.html

<!DOCTYPE html>
<html>
  <head>
    <title><!-- @siteTitle --></title>
  </head>
  <body>
    <!-- #content -->
  </body>
</html>

Rendered path/to/target/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Alternator</title>
  </head>
  <body>
    <h1>Welcome</h1>
    <p>Hello, world!</p>
  </body>
</html>

Pro Tips

Use ?? to assign a default value: 
Any comment syntax works: , /* @foo */, or // @foo