⪼ Made with 💜 by Polyglot.
We will be creating a Gist-based blog engine.
Blog posts are sourced from GitHub Gists. For each new blog post, there will be a new Gist created with the filename "readme.md". The blog post will be written in markdown in the "readme.md" file. The Gist description will serve as the as the title for the post. Markdown heading will correspond to HTML headers as appropriate. Fenced code snippets will be styled as appropriate.
I don't like writing on medium
⪼ Made with 💜 by realpolyglot.com
I don't like the medium writing experience. Imagine trying to write a technical blog post using Microsoft Word; well, writing on medium is slightly less painful than that, but barely.
Maybe I'm a bit spoiled; it is what it is. I like using the tools that have proven themselves on merit to be best in class:
- vim keybinding are a superpower
- Git for versioning is the only sane off the shelf option
- Markdown ... 🥰
- Configuration is specified via a "content.json" file.
-
"index": "https://gist.github.com/{user}/{id}"is a pointer to a "readme.md" that specifies "published" or "archived" Gists denoted by level-two headers (i.e. "## published", "## archived").
-
- Each content item is specified under the "## pubished" heading in "content.json"
- Each content item is specified in it's own Gist within a "readme.md" file
- Each content item has a title specified via the Gist's "description" field
- Each content item has a header specified via the level-one header (i.e.
# ...) - Each content item has a sub-header (optional) specified as a quote directly following the level-one header (i.e.
> ...) - Each content item has a hero image (optional) which directly follows the header/sub-header specified by
 - Each content item has body text which is any text written underneath the header/sub-header including all level-two and below headers
- Each content item when rendered to HTML will include an anchor for each level-two and below header
- For the rendering engine, the latest versions of Node.js and TypeScript will be used.
- For styling the HTML of the blog post, Tailwind CSS will be used.
- For rendering markdown to HTML, use the most modern and flexible markdown parser that is compatible with typescript and ESM modules.
- For unit testing, use the intrinsic Node.js test runner (i.e.
"node:test")
The problem with most blogging frameworks is that they either give the author/owner too little control or way too much control.
Most blogs do not provide a great writing experience. You're usually writing in some sub-par browser-based editor which is essentially a glorified text-box. For a software engineer, or anyone half-way technical, this is always a sub-par experience.
Some blogs expose a rich-text editing interface. This is a little bit nicer because the author visualize roughly how the content will look once published while authoring the content. This is a much more convenient experience. The problem with editing content in a rich-text environment is that there is finite control over the layout. In such environments, the content from blog-to-blog looks essentially the same. It's easy to tell when you're reading a medium.com blog. This may be a plus in some cases; however, it isn't always a win; otherwise, everyone would just use medium. I use medium sometimes; however, if the experience was better, I'd write there a lot more.
Personally, I don't always find it convenient to write my articles via their editor. Sometimes, I just want to write things up in a Gist, in markdown format. I've tried writing the initial content in markdown and pasting the markdown into the medium.com editor. It's almost what I want, but, I still have to make a lot of edits to get what I really want.
I'd prefer to have more flexibility in customizing the layout and have the ability to write the content in markdown format; perhaps in a Gist.
A blogging engine is essentially, a slimmed-down CMS or content management system; and, rightfully so, because, maintaining a blog is a pretty low-tech endeavor. The bells and whistles of an enterprise-level CMS is typically overkill. So, what content-managent features does a typical blog need:
- Custom Meta-Data: I want to be able to define custom meta-data for each blog I own.
- Strongly Typed Page Types: I want to be able to define a page type with it's own custom meta-data and before publishing, be able to validate that the correct meta-data has been provided.
- Markdown based: I want to be able to write content and meta-data in a text-based format so I am not tied to any specific editor. I want to be able to write content in vim, vscode, or whatever editor I choose.
It is well-established a blog's content should be statically generated. There's no need to generate content on the fly. It's a waste of computing resources. Static generation means that your cost to serve the content is astronomically cheaper. Storage is cheap and CDNs are cheap.