Futuramerlin Web Toolkit

The Futuramerlin Web Toolkit is a static site builder and theme featuring:

Version 2.2.35 would normally have been numbered 2.2.34, but was mistakenly given the number 2.2.35.

Documentation

Command syntax

Before running the Futuramerlin Web Toolkit, cd to the directory that contains the contents of your Web site. Note that those should be the only files present in that directory.

If using Wreathe 7.3 or the ebuild from the Wreathe overlay:

~/.futuramerlin-web-toolkit-build

~/.futuramerlin-web-toolkit-build

Otherwise:

~/.futuramerlin-web-toolkit-build

Installation

For Wreathe 7.3, an ebuild (app-misc/futuramerlin-web-toolkit) is available in the Wreathe overlay (this may also work for similar operating systems such as Ututo XS GNU/Linux).

For other operating systems, use the following installation instructions.

Download

git clone https://github.com/ethus3h/futuramerlin-web-toolkit.git

Setup

  1. Ensure your system has the correct dependencies:
    • Only tested and supported using GNU/Linux operating systems. It may be possible to run it using other UNIX-like operating systems, but that is not currently supported.
    • Requires a connection to the World Wide Web able to access GitHub.
    • Git
    • Perl
    • cpan
    • Node.js
    • html-minifier
    • html5-tidy
    • minifier
    • hypertoc: to install, run: sudo cpan -f -i HTML::GenToc
    • autoprefixer: to install, run: sudo npm install --global postcss-cli autoprefixer
    • Python 2, runnable as python2 (for installing and updating)
    Needed for the optional local CSS installation:
    • sudo privileges on your computer
    • A writeable root partition
  2. If you have a version of the Futuramerlin Web Toolkit prior to version 2 installed, remove it.
  3. Substitute the name of your Web site in place of "webSiteName" in the following command, and run the resulting command (note that output beginning with "mv: cannot stat" can be safely ignored):
    mv ~/.futuramerlin-web-toolkit.cfg ~/.futuramerlin-web-toolkit.bak; echo "webSiteName" > ~/.futuramerlin-web-toolkit.cfg
  4. Note that enabling the local CSS installation option will overwrite CSS files in your root directory if they have the same name as an included theme. In addition, if you have a case-insensitive filesystem, it probably will overwrite any files with names that are the same as that of an included theme when lowercased.
    If you want to enable the local CSS installation option (copies the Web site's theme CSS so the site can be more accurately previewed locally), run the following command:
    echo "enableLocalInstallation" >> ~/.futuramerlin-web-toolkit.cfg; set +H

    Otherwise, run the following command:
    echo "disableLocalInstallation" >> ~/.futuramerlin-web-toolkit.cfg; set +H
  5. Run the following command:
    futuramerlinWebToolkitPreInstallPath=$(pwd); futuramerlinWebToolkitInstallationUUID=$(python2 -c 'import uuid; print str(uuid.uuid4())'); cd ~; mkdir "$futuramerlinWebToolkitInstallationUUID"; cd "$futuramerlinWebToolkitInstallationUUID"; git clone https://github.com/ethus3h/futuramerlin-web-toolkit.git; cp -f ./futuramerlin-web-toolkit/futuramerlin-web-toolkit-build ~/.futuramerlin-web-toolkit-build; chmod +x ~/.futuramerlin-web-toolkit-build; cp -f ./futuramerlin-web-toolkit/futuramerlin-web-toolkit-aliases ~/.futuramerlin-web-toolkit-aliases; chmod +x ~/.futuramerlin-web-toolkit-aliases; echo $(date +%Y-%m-%d-%H-%M-%S-%N)-$(xxd -pu <<< "$(date +%z)") >> ~/.futuramerlin-web-toolkit.cfg; echo "$futuramerlinWebToolkitInstallationUUID" >> ~/.futuramerlin-web-toolkit.cfg; echo "#"'!'"/bin/bash" >> ~/.bash_profile; echo ". ~/.futuramerlin-web-toolkit-aliases" >> ~/.bash_profile; echo "#"'!'"/bin/bash" >> ~/.bashrc; echo ". ~/.bash_profile" >> ~/.bashrc; chmod +x ~/.bash_profile; chmod +x ~/.bashrc; cd ..; rm -r ./"$futuramerlinWebToolkitInstallationUUID"; cd "$futuramerlinWebToolkitPreInstallPath"
  6. Log out and log in again, to update your shell aliases.

Themes

common
Components shared between the other themes.
ember
No longer maintained! A fancy theme designed to look like the default theme in version 7r2 of the Wreathe GNU/Linux distribution. This is the theme that was formerly used for the Ember project Web site. Despite the name, it is no longer currently used for that (the "simple" theme is used instead), and isn't actively maintained. WARNING: This theme has a bug in the CSS that causes it to malfunction badly when pages using it are viewed in Netscape 6–era Web browsers, causing the Web site to be unusable as the navigation menu fills the entire viewport.
m
Alias for the "ember" theme.
simple
A simple black-and-white theme. This is the theme used for the Ember project Web site.

Ebook configuration

Each line consists of a "depth", followed by a space, followed by the line's contents. The line may be preceded by whitespace without breaking anything, allowing for nicely formatted files. The depth can be any of the following values:

#
Comment
Integers -1+
Include the specified path, adjusting its headings by the number of depth levels given. The path may be a path without extension to a .htm file in the Web toolkit's expected fragment format, or the path to a directory ending in / containing a file index.htm in the usual format, or the path with or without extension of another ebook configuration file. If the level -1 is given, headings at the top level will be removed (but any text within them will remain); this is intended for use with a file with a single <h2> header which is desired to be a top-level part of a book.
-2
A path without extension of a file present with the extension of the native target output format(s), of which to include the contents literally. (For example, if you want the file included for the htm and plain.html output formats of the book, and your configuration line is "-2 book-assets/include-me", the files book-assets/include-me.htm and book-assets/include-me.plain.html need to exist.)
-3
A heading to include literally, like "<h3>Heading Text</h3>". (It will be adjusted as needed if the book is included in another book.)
-4
Used as the first line of a configuration file to define the book title, e.g. "-4 Book Title"

Configuration file format

The configuration file is located at ~/.futuramerlin-web-toolkit.cfg. It contains configuration values separated by a line feed (0x0A), as follows:

Note that there is currently no facility for storing configuration values containing line feeds.

Development

To learn about contributing to this project, visit the development page.