~codersonly/transmogrifier

A static website generator
add one more file test case
simplify deno file system operations
create an upload file matcher

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~codersonly/transmogrifier
read/write
git@git.sr.ht:~codersonly/transmogrifier

You can also use your local clone with git send-email.

#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

Coming soon...

#Documentation

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

#Configuration

Coming soon...

#Simple Markup

Coming soon...

#Advanced Features

Coming soon...

#Special Characters

Coming soon...

#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

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.

#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...

ZAP

Copyright Calvin and Hobbes, © Andrews McMeel Syndication 2021.