~codersonly/transmogrifier

#Transmogrifier by Coders Only

Transmogrifier by Coders Only, a static website generator, is a collaborative effort by the members of the Coders Only software craft community. We're grateful for all individual contributions but attribute the entire project to the community.

The markup language of Transmogrifier is called ZAP. About the origin of these names see the bottom of this file. The primary goal of Transmogrifier is to allow us migrate our website away from WordPress. This will drive the required features.

Any questions or feedback, hit us up.

#Getting Started

Transmogrifier works by reading a directory with the sources of website and generating another directory that can then be uploaded to a web server.

#Requirements

You'll only need the Deno runtime. Install it the most convenient way.

#Installation

Download (or clone) the repository and place it in a cozy spot in your file system. Then, for best results, add the .../bin folder to the system PATH.

#Usage

Transmogrifier needs a zap.conf file and a source directory to work. Then it can be summoned via zap (imagine an exclamation mark following the command, it's more fun that way). On success it generates an upload directory with the contents of your website. You can start a local web server to preview the results, e.g. via ruby -run -e httpd upload -p 9090.

#Documentation

Here we detail all supported functionalities of Transmogrifier and the specifics of the ZAP markup.

Transmogrifier works by copying all contents of the source directory over into a new upload directory (removing any existing content beforehand). Files with a .zap extension undergo markup expansion and get their .zap magic purged, so e.g. index.html.zap becomes index.html.

#Configuration

The zap.conf file must exist but can in theory be empty. It's to contain variable definitions in the form key: value. Padding whitespaces will be ignored, the value is terminated by the end of the line. Multiline values can be defined by starting with a key: line only, such blocks are terminated by an empty line.

The values of variables with the keys ext.head: and ext.tail will be injected before and after the contents of filename.ext.zap files.

The existence of a base_url variable instructs Transmogrifier to also generate a sitemap.xml file.

An example file, also demonstrating the expansion of a page_title variable defined in the individual html files:

base_url: https://your.doma.in

html.head:
<!DOCTYPE HTML>
<html lang="en">
  <head>
    <title>Site Name - { $ | page_title }</title>
    <link rel="stylesheet" type="text/css" href="/stylesheet.css">
  </head>
  <body>

html.tail:
  </body>
</html>

#Simple Markup

Coming soon...

#Advanced Features

Coming soon...

#Special Characters

To put curly braces in the content escape them as {hello} → {hello}.

#Architecture Decision Records

A few notes on why certain things turned out this way.

#Yet Another Markup

ZAP is a trivial HTML based markup. It does not introduce syntactic elements that need to be remembered, like single or double asterisks, instead it always uses HTML tags. It also tries to eliminate the confusion with other classic Markdown features, like adding links, and provides simple means to specify style attributes.

#TypeScript on Deno

We needed a language that's fairly standard, lightweight and relevant because want to use the project for exercises in our workshops, and the lower the barrier to entry, the more interesting the concepts, the better it will be for participants. The lightweight requirement disqualified compiled languages, the standard eliminated the (lovely but) exotic ones, so with TypeScript being an ideal candidate, the existence of the amazing new Deno runtime won the race.

But for completeness' stake, beside TypeScript the other candidates mulled over were Odin, Lua, Pike, V, Elixir and Crystal.

#No External Dependencies

This being a command line tool, despite the purpose of website generation, we want to stick to a strict "no further dependencies" policy, to the point of being able to run the tool offline. And keeping things simple we don't want to add a local package cache. Hence we shall stick to the inbuilt means of Deno. Also, to gain experience with whatever feats it has and what it's missing. Also, to see what does it take to fill those gaps. As mentioned before, learning exercise.

#Unix Derivatives Only

Yeah, sorry, we aren't going to deal with backslashes and drive letters and the rest of Redmond. If Transmogrifier is going to run in the Linux mode of Windows, we'll be glad, but if it won't... too bad.

#Functional or OO

We were bored with all things ever ending up in OO so chose to push things functional ways. For funs and excitements and learnings.

#Numeric Character References

The reason for using numeric character references - e.g. ä for ä - is that some feed readers we tested with did not render named character references - e.g. ä - properly. So, while uglier, we went with the safer variant.

#Latest Standard Library

The Deno manual recommends pinning the version of the standard library in the import statements but we don't do that (yet). The reason is that with both Transmogrifier and Deno being in active development staying on the latest paradigm is more important than stability. After the first release we'll probably revisit this decision.

#Development & Troubleshooting

#Deno Support

Unfortunately Deno support in WebStorm is currently not perfect but it's better than nothing, so activate it.

#Code Format

Strict Deno compliance for sources, as by the deno fmt command - though NOT for Markdown files because that formatter is very flaky still. So use the bin/transmogrifier-formatter command or add its equivalent to your IDE.

#Code Cleanliness

All code is to be kept fully clean when using the default inspection settings of WebStorm. This means that all files must display an undecorated little green tick in the top-right corner. Don't suppress warnings locally because they will bite others. And use noinspection sparingly too - aim at clean code!

Note: do NOT open the lib/deno.d.ts file in WebStorm because that's chock full with warnings that can only be suppressed individually so we don't clean that file up (apart from reformatting it). But all things work fine if it stays closed.

#Creative Commons License

Transmogrifier by Coders Only is licensed under the GNU GENERAL PUBLIC LICENSE v3.

To view a copy of this license, visit https://www.gnu.org/licenses/gpl-3.0.html.

Transmogrifier by Coders Only, a static website generator

Copyright (C) 2021 Coders Only, https://codersonly.org

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses>.

All individual contributions are attributed to the Coders Only community.

#ZAP!

The name Transmogrifier is with a nod, or rather, bow, to Calvin and Hobbes and their creator, Bill Watterson.

And "ZAP" comes from...

refs

clone