About
Microcosmos is a blog server. It really doesnt do very much at all; it just does exactly the things I would want from a blog CMS.
Heres the list of features:
Powered by Pandoc for maximum input-file-agnosticism. You can write blog posts in Markdown, LaTeX, or even Microsoft Word and they will be rendered as nicely typeset web pages.
The entire program is only about 300 lines of readable Haskell code.
Everything about the blog is designable at runtime. You can edit the css files, obviously, but you can also change the default layout using the Shakespeare template files.
As soon as you edit a post, the changes are visible.
The distribution is a single, portable binary.
Despite doing quite a lot of stuff for you, its speedy. Its built on top of the Yesod web framework and the Warp webserver, both of which are well optimised.
Zero frontend load - the site is a normal website - no hefty frontend frameworks. When rendering my blog, a page weighs about 70kB - 64kB of which is the header font.
How to use
Installation
Either download the latest binary release, or clone the repository and compile with the stack build tool.
Usage
To start mc, simply run the mc executable from the root
of your blog.
The program is slightly opinionated about where things should be (although you can always symlink). It wont run if it cant find some template files at a minimum.
postsis for all the content you wish to display.staticis for all the resources to be accessed alongside that content.templatesis for the HTML scaffolding of the website.templates/layout.hamletis the outer scaffolding for the entire site - resources to be loaded on every page go here.templates/folder.hamletdescribes the layout of autogenerated folder indices.templates/post.hamletdescribes the layout of posts.
Hamlet files are like HTML files, but closing tags are omitted in favour of indentation based semantics, and they support variable interpolation.
By default, mc will render any file in
posts as an HTML document, based on the filename. In other
words, it determines the URI slug from the filepath. There is one main
exception: home will be rendered both for
https://my.blog/ and https://my.blog/home.
Dotfiles are ignored and will not be rendered by mc.
Metadata
You can provide limited metadata about your content in a preamble. Start a post with a hyphen-fenced block:
------------
title: Microcosmos - a Tiny Blog
date: 2019-11-02 10:00
------------
## About
Microcosmos is a ...and the title and date will be appropriately reflected on posts and in directory listings. Without a preamble, the post will use the filename as the title, and the files modified time as the post date.
Known issues
Even though its functionality is deliberately tiny,
mcis really, really huge. This is a known issue with GHC binaries in general. If you compile it from source (and therefore have the libraries on your computer) you can add the-dynamicoption to GHC which will reduce the total size from >100MB to ~250kB (!!). Theupxutility is also very effective at shrinking binaries, shrinking from >100MB to ~14MB.mcis also the short binary name ofmidnight-commander, the terminal file manager.The system is not optimized for performance, although laziness should help avoid the worst excesses. It should only read the preamble of posts in order to get the titles, for example.
Some errors show up when reading in filetypes for which pandoc only has recent support; eg.
.odtfiles should be readable but seem to throw errors. Markdown is still the first-class filetype for posts.
Future work
Online editing is a maybe. It seems out of the scope of
mcso I might leave that as an exercise to the reader.Preview / Draft mode so that pages automatically update when updated, and maybe dont show up in directory listings.