README
sniplicity
Simple comment-based static HTML build system that lets you reuse code snippets with simple variables and conditional inclusion. Great for building static websites with less hassle.
- static page builder
- all commands are embedded in HTML comments
- re-use snippets of HTML throughout your project
- use variables to replace values and control your build
- include other files
Install
From NPM
Globally
sudo npm install -g sniplicity
or locally
npm install -s sniplicity
From GitHub
git clone https://github.com/davebalmer/sniplicity.git sniplicity
cd sniplicity
npm i
Run
Globaly:
sniplicity -i in_dir -o out_dir
or locally:
node sniplicity.js -i in_dir -o out_dir
Currently sniplicity only supports the concept of a source (in) directory and a destination (out) directory, which it uses to:
- read all
html
,htm
andtxt
files found in thein
directory - process them
- save compiled files to the
out
directory
In the future, sniplicity should also accept single files to process to make it compatible with other build tools.
Options
Flag | Short | Purpose |
---|---|---|
--in | -i | Input (source) directory |
--out | -o | Output (destination) directory |
--watch | -w | Watch the in directory and your project when one or more of them change. |
--verbose | -v | Increase the sniplicity inner-monologue. |
--help | -h | Help! |
Commands
All sniplicity commands are embedded in HTML comments, so they will not intefere with your favorite editor. Here are some examples:
<!-- set test -->
<!-- set title Hello World -->
<!-- if test -->
<h1>--title--</h1>
<!-- endif -->
<!-- cut footer -->
<footer>
Copyright © 2016
</footer>
<!-- end footer -->
<!-- paste footer -->
<!-- include disclaimer.html -->
cut
and copy
Marking snippets with Snippets work like a text editor clipboard. Use cut
, copy
and paste
to define and use snippets. You may cut or copy them anywhere in your project and they can be pasted anywhere in any file (even the one they were defined in).
<!-- copy nav -->
<p>
Nav: A, B, C<br>
(will show up twice because we copied it)
</p>
<!-- end -->
<!-- cut footer -->
<p>
Copyright © 2016 A, B, C<br>
(only shows up once because we cut it)
</p>
<!-- end -->
Both cut
and copy
make snippets. The
difference is copy
will copy the snippet while, you guessed it,
cut
will cut it out of the current file. When in doubt, use copy
.
paste
Pasting snippets with To use any snippet, just paste
it by name in any file in your project.
<!-- paste footer -->
<!-- paste nav -->
set
Assigning variables with These are more like constants, and you use set
to define them. Their values are available only inside the file where you set
them, and the last declaration in a file will have the value used for replacement.
<!-- set test -->
<!-- set message Hello World! -->
--variable_name--
marks
Using variables with With any variable (or default variable), you may include the value by using a simple mark anywhere in your file with the name of the variable surrounded by two dashes.
<!-- set title Hello World! -->
<title>My title is --title--</title>
global
Make global default variables with You may set global default values for variables with default
. If you use set
with the same variable name in a given file, the default value will be overwritten inside that file and return to its default value for other files.
<!-- global development -->
<!-- global title My Website -->
You may also use these defaults as a form of global variable which you can use anywhere in your project.
if
and endif
Make conditional builds using You can test a variable to decide if you want to include or exclude a section. These will work inside snippets as well.
<!-- if test -->
test is truthy!<br>
<!-- endif -->
<!-- if !test -->
test is falsy!<br>
<!-- endif -->
include
Include other content files using Right now, sniplicity copies the file contents verbatum. Later there may be filters (eg. markdown, jade).
<!-- include metatags.html -->
About
This build tool scratches an itch I had for a static HTML builder that could move easily from single-page design prototype to multi-page production site with incremental and minimal automation effort. It is a conceptual reboot of a tool I designed and wrote back in my perl
days, but simplified and more focused.
Templates (not exactly)
Sniplicity is not a template engine so much as a tool that lets you "short-cut" the more redundant efforts of producing hand-coded HTML by using code snippets, simple variable substitution, and conditional code and file inclusion.
That said, it's designed to be completely compatible with template tools like Jade, Backbone, Handlebars, LESS, Stylus and the like. It just allows you to automate your static HTML file building.
Roadmap
The features and syntax for the first release are set, but more extensive error checking is a must. I also want to make the features that are there smarter and more flexible.
Contributing
Yes! Let me know of any errors or feature requests in the issue tracker. If you want to take a stab at making improvements, please do. Nothing special is required, just clone this repo and start coding. I'm open to all good pull requests.
License
Copyright (C) 2016 Dave Balmer Using the MIT License (MIT)