mathblog: A program for creating and managing a static, mathematically-inclined weblog

[ bsd3, program, web ] [ Propose Tags ]

This package provides a program for creating and managing a statically-generated, VCS-friendly, mathematically-inclined weblog. If you're interested in managing a blog with few moving parts and support for embedded LaTeX math and the UNIX editor of your choice, then this is the blogging platform for you! For detailed information, please see the README.

[Skip to Readme]
Versions 0.1, 0.2, 0.3, 0.4, 0.5, 0.6
Dependencies base (>=3 && <5), directory (==1.0.*), filepath (==1.1.*), old-locale (==1.0.*), pandoc (==1.6.*), process (==1.0.*), time (==1.1.*), unix (>=2.3 && <2.5) [details]
License BSD-3-Clause
Author Jonathan Daugherty <>
Maintainer Jonathan Daugherty <>
Category Web
Home page
Uploaded by JonathanDaugherty at Wed Sep 1 04:15:40 UTC 2010
Distributions NixOS:0.6
Executables mb
Downloads 1879 total (18 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2016-12-29 [all 7 reports]
Hackage Matrix CI


Maintainer's Corner

For package maintainers and hackage trustees

Readme for mathblog-0.1

[back to package description]

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

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


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:


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


    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.

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.

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:
  Processing: second-post
  Generating all-posts list.

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:


    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.


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


    These files make up the HTML content surrounding the post body

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;


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