A quick, simple server-side-includes expander.
What's server-side includes?
Server-side-includes (SSI) is one of the directives that most popular web servers like
httpd (Apache) and
nginx implement, that allow for "dynamic" construction of HTML without having a dynamic application running. You can decompose an HTML page into separate page parts, and "include" them using an HTML comment-like "include directive" in the HTML.
An SSI in action looks like this;
<html> <head> <title>Main page</title> <!--#include virtual="/parts/head_part.html" --> </head> <body> <!--#include virtual="/parts/page_header_part.html" --> <main>...</main> <!--#include virtual="/parts/page_footer_part.html" --> </body> </html>
The web server will attempt to parse the HTML for the include directives, and dynamically fill them in when the page is served.
Dessi will take an entire site (or parts of it, if told to), expand out the include directives as if they were being served by a web server, but save those files instead to disk, so you have a fully static version of the SSI site.
Why an expander?
I recently had to migrate an SSI-enabled static site out of a controlled environment with SSI into a completely static host. Rather than build a specific script to do the "expansion" into a completely static site, I wrote Dessi to make the process generalizable to my other static sites.
Install and use
Install with npm. Dessi is designed to be installed globally as an NPM package:
# with the npm package manager npm install --global dessi # ... or with the yarn package manager yarn global add dessi
And that's it! Invoke Dessi by going to a directory that contains the files you'd like to expand, and run:
dessi --source=<source directory> --target=<target directory>
If you've used
npx, you can also just run Dessi as a package with
npx dessi <...options> without installing anything.
You'll find more instructions in the Manual section below.
Dessi takes three command line arguments:
--source: the source directory. Usually, I'll
cdto this directory and just pass
--source=.. This directory is also assumed to be the root of the website
/, unless a
--rootoption is specified.
--target: the target or destination directory for the expansion. All files and folders in the source directory will be copied into this directory with the exception mentioned below (*). This is usually my
build/directory of the project, and
--root (optional): if the "root" directory of the static site (where index.html usually lives) is different than the
--sourcedirectory, You can explicitly specify a different root directory to use in the expansion of files in the SSI directives. Otherwise, Dessi will default to the source directory specified.
dessi --root=. --target=./dist --source=.
Note that Dessi explicitly requires you to use the
= sign to specify options. This is something I'd like to fix but haven't had the time to yet, as it works fine without this functionality.
[*] Most of the time, I'd like to expand the contents of everything in a repository into a static folder within that repository. Dessi handles this use case by ignoring the destination folder if that folder is nested within the source folder.
$ ls . mydir/ destdir/ other_files.html $ dessi --source=. --target=./destdir [...] # output abridged $ ls destdir mydir/ other_files.html # destdir/ is missing, since it was the target directory
These are things I'd like Dessi to be able to support, but haven't had time to add yet.
- Support for replacing / expanding files in-place without copying.
- Support for specifying options without the
- Generally better and more helpful error handling.
Dessi is licensed under the permissive MIT License. See
LICENSE for more information.