CSI -- client-side includes - is an ad hoc informally specified tool for processing a directory of text files. It allows you to define files that include other files, and substitute variables.
The primary use-case is to make building pure HTML sites a little bit easier.
- Process a directory of files
- Include files in other files
- Set variables to arbitrary values
- Include environment and scoped variable values in files
You can find static binaries for Linux and macOS on the Github Releases page.
Alternatively, you can use cargo
to install the tool on any platform that Rust supports.
cargo install csi
csi <input-directory> <output-directory> [--ext <extension>]...
For example, given the following command:
csi src target/dist --ext .html --ext .css
CSI will walk the input directory and process all files.
- If a file begins with
_
it will be skipped. - If a file ends in
.html
or.css
, it will be processed and written to the output directory. - If a file doesn't, it will be copied verbatim to the output directory.
Note that the directory structure is perserved.
CSI's features are provided via directives which are simple statements in your files. Directives are enclosed in []
-- e.g. [include raw my-file.html]
. A directive is a space separated list of arguments.
To simplify its behavior, CSI does not trim white-space. If a directive cannot be parsed, the program exits with a failure.
You can use the var
or opt
directives to substitute environment variables into the file. var
indicates that the variable is required, while opt
indicates it is optional.
If a variable isn't defined, and opt
is used, the directive will evaluate to the empty string.
var <format> <variable>
opt <format> <variable>
Format may be html
or raw
. If html
, it will be escaped for use in an HTML document. If raw
, it will be substituted directly.
When using raw
, be sure that you're not subjecting yourself to XSS attacks.
<p>Hello [var html MY_VAR]</p>
You can set a variable for use in the current file or included ones.
set <name> <value>
[set name John]
[include raw _template.html]
Stash will take all of the current evaluated content and place it into the specified variable. Content after the stash directive is excluded. This is useful for defining some content in a file, and then evaluating it in the context of a template that renders variables. Also known as the decorator pattern.
stash <variable>
<p>This is my content</p>
[stash content][require _layout.html]
You can include files in other files. If a file includes a file that includes itself, that include will be ignored to break the cycle.
File paths are relative to the file that is being processed.
If the file doesn't exist, the directive will evaluate to the empty string.
include <format> [path]
Format may be html
or raw
. If html
, it will be escaped for use in an HTML document. If raw
, it will be substituted directly.
When using raw
, be sure that you're not subjecting yourself to XSS attacks.
<pre>[include raw /etc/passwd]</pre>
You can require files in other files. If a file includes a file that includes itself, the program will exit with a failure.
File paths are relative to the file that is being processed.
If the file doesn't exist, the program will exit with a failure.
require <format> [path]
Format may be html
or raw
. If html
, it will be escaped for use in an HTML document. If raw
, it will be substituted directly.
When using raw
, be sure that you're not subjecting yourself to XSS attacks.
<pre>[require raw /etc/passwd]</pre>
- Fix a bug breaking
[var html <name>]
usage
- No functionality changes.
- Built and released using automated pipeline on TravisCI.
- Initial release.