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.
Transmogrifier works by reading a directory with the sources of website and generating another directory that can then be uploaded to a web server.
You'll only need the Deno runtime. Install it the most convenient way.
Download (or clone)
the repository and place it in a
cozy spot in your file system. Then, for best results, add the
to the system
Here we detail all supported functionalities of Transmogrifier and the specifics of the ZAP markup.
A few notes on why certain things turned out this way.
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.
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.
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.
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.
We were bored with all things ever ending up in OO so chose to push things functional ways. For funs and excitements and learnings.
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.
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.
UPDATE: the below section is not relevant anymore, just activate Deno support for the project in WebStorm.
TO BE REMOVED: The
lib/deno.d.ts file exists solely for the purpose of stopping WebStorm complaining about
Deno not being defined. It is generated manually with the
deno types > deno.d.ts command and should probably be updated from time to time.
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.
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.
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.
And "ZAP" comes from...
Copyright Calvin and Hobbes, © Andrews McMeel Syndication 2021.