@hackage mathblog0.1

mathblog

mathblog is a Haskell program targeted at people who want to write statically-generated, mathematically-themed weblogs.

Project vision

I wrote mathblog with a very specific set of requirements in mind, motivated by the following principles:

• a blog should be easy to create, host, and update.

• a blog should be easy to maintain.

• I should be able to edit posts in my editor of choice and write them in an intelligent textual markup language.

• It should be easy to embed high-quality mathematical symbols and equations in the blog posts.

As a result, mathblog has the following properties:

• the software is composed of a single executable which will automatically take care of creating your blog and regenerating pages when your post markup changes.

• all content is stored in plain text files and is generated statically. No database, web framework, or templating system is used.

• a mathblog can be hosted with a simple static fileserver such as thttpd, lighttpd, or apache.

• blog posts are written in the Markdown format with extensions, as supported by the Pandoc document converter.

• Math is embedded with \(...\) and \[...\].

These properties have some nice advantages; your blog content is cacheable and can be subjected to revision control. Posts are easy to edit and editing doesn't require a web browser. The static file representation model means you can compose a blog post on your laptop and get it just right using a local installation of mathblog, then push it up to your server to post it to your public blog.

Dependencies

mathblog takes advantage of three primary software components:

• pandoc, which will be installed for you automatically if you use "cabal" to install mathblog. For best results, use the revision control version of Pandoc.

• gladTeX, a package of tools for rendering LaTeX equations. At present you MUST get gladTeX from revision control, since mathblog requires features not yet released.

• a TeX distribution, such as TeX-live

How to use

mathblog doesn't have any persistent configuration file; the way you configure it is by setting two environment variables:

MB_BASE_DIR

The location of your blog files on the filesystem.  Must be an
absolute path.

MB_BASE_URL

The base URL of your blog as it will be hosted.  This is used to
generate fully-qualified URLs.  A trailing slash is not expected.
E.g., "http://localhost:8080".

Once you've set those environment variables, just run "mb". It will take care of setting up a new blog data directory for you, complete with some default pages and a default first blog post:

$ export MB_BASE_URL="http://localhost:8080" $ export MB_BASE_DIR=pwd/myBlog $ mb mb: using base directory "/home/.../myBlog" mb: using base url "http://localhost:8080" Setting up data directory using skeleton: /home/.../.cabal/share/mathblog-0.1/skel Processing: first-post Generating all-posts list. Done.

Now you have a blog; fire up a web server pointing at myBlog/html and you'll see a demo post.

Next, you might want to edit or create a new post, or even remove one. Just edit the appropriate file in myBlog/posts/ accordingly and re-run mb. Here's an example of adding a new post:

$ mb mb: using base directory "/home/.../blog/myBlog" mb: using base url "http://localhost:8080" Processing: second-post Generating all-posts list. Done.

Post format

Posts are formatted in Markdown and support the extended Markdown syntax as implemented by Pandoc. The only important convention to note is that the post title goes on the first line of the file following a percent sign, as follows:

%My First Post

First paragraph starts here.

Running mb in "listen" mode

Ordinarily, you'll just run "mb" once in a while to update your content. But if you're in the middle of authoring a new post and you want to see what it looks like as you edit it rather than run "mb" by hand periodically, you can run "mb" in "listen" mode; this means that mb will run forever, peroidically scanning the filesystem for changes to your blog posts and other data files and regenerate them when it detects a change. Running mathblog in listen mode is simple:

$ mb -l mb: using base directory "/home/.../myBlog" mb: using base url "http://localhost:8080"

Changes detected: /home/.../myBlog/posts/second-post.txt Processing: second-post Generating all-posts list. Done.

Above I ran "mb" in listen mode and then modified one of the posts, second-post.txt, and "mb" detected the change and ran its typical regeneration routine.

Customizing your blog

It's likely that you'll want to customize the look and feel of your blog. To this end, mathblog generates the pages of your blog by assembling various pieces of the page to create the final result. The biggest piece of a generated page is the blog post itself, but the surrounding elements are read from various files that are created by mathblog when it creates your blog data directory. These files are stored in the "templates/" subdirectory of your blog data directory and are as follows:

templates/rssPreamble.xml templates/rssPostamble.xml

These files make up the leading and trailing RSS XML that will be
used to wrap the individual elements of your blog's RSS feed.
You'll probably want to change the rssPreamble.xml file, since it
contains information about the blog author.

templates/pagePreamble.html templates/pagePostamble.html

These files make up the outermost HTML content of the blog post
pages, including the index page and the post list page.

templates/postPreamble.html templates/postPostamble.html

These files make up the HTML content surrounding the post body
itself.

In addition, subdirectories of the "html/" directory contain things you might want to customize, such as a CSS stylesheet.

Other features

Since mathblog doesn't provide many moving parts, it's up to you to outsource various web site features, such as comments. I've successfully integrated mathblog with the Disqus comments service. To do this, some javascript needs to be embedded in the blog pages. Disqus works best when you supply it with a page identifier so it can guarantee that comments are post-specific rather than URL-specific. The way mathblog makes this possible is by exposing a JavaScript variable to other scripts in your page:

Blog.pageName = "foobar-baz";

This variable name can be used by scripts you embed, such as with Disqus comment forms:

var disqus_identifier = Blog.pageName;

Afterword

I personally use this software package but I'll be pleased if others find it useful. In addition, I'm open to accepting contributions on the project if they're consistent with what I've outlined above. Happy blogging!

Jonathan Daugherty drcygnus@gmail.com