mathblog-0.6: doc/mathblog-manual.tex

\documentclass[11pt, letterpaper, oneside, titlepage]{book}
% Use Palatino fonts.
\renewcommand{\rmdefault}{ppl}
\renewcommand{\ttdefault}{pcr}

% For smarter references.
\usepackage{varioref}

% For embedding the output of "mb" usage demo scripts.
\usepackage{fancyvrb}

\usepackage[usenames,dvipsnames]{xcolor}

% For hyperlinks.
\usepackage{hyperref}
\hypersetup{colorlinks,citecolor=blue,%
            filecolor=red,linkcolor=blue,%
            urlcolor=blue}

\usepackage{tikz}
\usetikzlibrary{intersections,backgrounds,fit,calc,positioning}
\usepackage{pgfplots}

% Customize document dimensions.
\addtolength{\hoffset}{-0.5in}
\addtolength{\textwidth}{1.0in}
\setlength{\topmargin}{0in}
\setlength{\parskip}{0.1in}
\setlength{\parindent}{0in}

\begin{document}

\include{macros}
\include{title_page}
\include{toc}

\chapter{Introduction}

\mathblog\ is a program targeted at people who want to write
statically-generated, mathematically-themed weblogs.  It supports:

\begin{itemize}
\item{Extended Markdown input syntax as supported by the Pandoc
  library}
\item{Inline and block-level \TeX\ math rendered by MathJax}
\item{Function graphing and drawing with the TikZ \LaTeX\ package}
\item{Support for integration of Javascript-based web services such as
  Disqus}
\item{Template-based document rendering with support for layout and
  style customization}
\item{A built-in web server with automatic page reloading for easy
  blog post authoring}
\end{itemize}

\section{Project Vision}

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

\begin{itemize}
\item{A blog should be easy to create, host, and update.}
\item{A blog should be easy to maintain.}
\item{I should be able to edit posts in my editor of choice and write
  them in an intelligent textual markup language.}
\item{It should be easy to embed high-quality mathematical symbols and
  equations in the blog posts.}
\end{itemize}

As a result, \mathblog\ has the following features:

\begin{itemize}
\item{The software is composed of a single executable which will
  automatically take care of creating your blog and regenerating pages
  when your blog post markup changes.}
\item{All content is stored in plain text files and is generated
  statically.  No database or web framework is used and no resident
  processes are required to serve your content.}
\item{\mathblog's generated output files can be hosted by any web
  server.}
\item{\mathblog\ provides a built-in web server for easy blog post
  authoring.}
\item{Blog posts are written in the Markdown format with extensions,
  as supported by the Pandoc document converter.}
\item{Math is embedded with \verb|$...$| (or \verb|\(...\)|) for inline math
	and \verb|$$...$$| (or \verb|\[...\]|) for block-level math.}
\end{itemize}

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

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 the goals I've outlined above.

Happy blogging!

\chapter{Using \mathblog}

The main program provided by the \mathblog\ package is the program
\fw{mb}.  This program takes care of initializing new blog data
directories, detecting changes in your files, regenerating the right
HTML output files into your output directory, and even serving them
via HTTP while you work.

\fw{mb} needs to know about two directories: the \textit{data
  directory} where your post input files and templates will be kept,
and the \textit{output directory} where the HTML version of your blog
will be generated.  \fw{mb} has two ways of knowing about both of
these directories: you can set environment variables or you can pass
command-line flags to \fw{mb}:

\begin{itemize}
\item{Data directory: set \fw{MB\_DATA\_DIR} in the environment or pass
	the \fw{-d} option to \fw{mb}.}
\item{Output directory: set \fw{MB\_OUTPUT\_DIR} in the environment or
	pass the \fw{-o} option to \fw{mb}.}
\end{itemize}

Any command line parameters given to \fw{mb} will always take
precedence over any environment variables.

\section{Step 1: Create}

Once you've chosen your data and output directories, run \fw{mb -i}.
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:

\blogexample{init}

The directory structure of the new blog data directory is as follows:

\begin{itemize}
\item{\fw{blog.cfg} - The blog configuration file.}
\item{\fw{posts/} - Blog post files (``\fw{*.txt}'').}
\item{\fw{posts/posts-index} - A special text file called the
  \textit{posts index}.  This file contains a list of posts in the
  order in which they should be listed on the blog.  It gets updated
  by \mathblog\ when new posts are created, but you can edit the file
  to change the ordering if you need to.  For more information, see
  Section \ref{sec:postsindex}.}
\item{\fw{templates/} - Templates used to generate the blog post
  pages, post listing page, and RSS feed.  These templates are
  StringTemplate templates.}
\item{\fw{assets/} - The directory where you can put arbitrary files
  to be copied to the HTML output directory.  \mathblog\ will copy
  \fw{assets/foo} to \fw{\$MB\_OUTPUT\_DIR/foo}.}
\end{itemize}

\section{Step 2: Configure}
\label{sec:configuration}

\mathblog\ creates a default ``INI-style'' blog configuration file in
your data directory called \fw{blog.cfg}.  It contains information
which may be included in the generated pages.  The configuration file
must have the following fields set:

\begin{itemize}
\item{\fw{baseUrl} - The base URL of your blog; this URL will be used
  to generate some links in the blog's pages where absolute URLs
  matter.  URL generation assumes that your blog is hosted at the root
  of a domain.  The base URL corresponds to the output directory.}
\item{\fw{title} - The title of your blog, such as "My math blog".}
\item{\fw{authorName} - Your name (for the RSS feed metadata and the
  page footer).}
\item{\fw{authorEmail} - Your e-mail address (for the RSS feed
  metadata only).}
\item{\fw{mathBackend} - The backend used to render \TeX\ math
  expressions.  Right now the only possible value is \fw{mathjax}.  No
  special configuration is necessary for MathJax, as \mathblog's
  default templates use CDN resources for MathJax.}
\item{\fw{tikz} - Whether to permit the use of the Tikz
  \LaTeX\ package to create diagrams and function plots.  Set to
  \fw{yes}, \fw{on}, or \fw{1} to enable.  Disabled by default.}
\end{itemize}

All of the above fields can be accessed in templates using the syntax
described in Section \ref{sec:customizing} below.

\section{Step 3: Edit}

Now you might want to edit or create a new post or remove one.  Start
by editing the appropriate file in \fw{posts/} and then run \fw{mb}.
To create a new blog post, just create a new file ending in
``\fw{.txt}'' in the \fw{posts/} subdirectory.  Here's an example of
running \fw{mb} after modifying an existing post:

\blogexample{changed-post}

Ordinarily, you might run \fw{mb} once in a while to update your
output directory.  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
\fw{mb} by hand repeatedly, you can run \fw{mb} in ``listen'' mode; in
listen mode, \fw{mb} will start a lightweight web server and serve
your blog locally while you edit it.  If you open a web browser to one
of your blog posts, it will automatically reload whenever you make a
change to one of your blog files!

Here's a listen mode example:

\blogexample{listen-mode}

Above I ran \fw{mb} in listen mode and then modified the posts index,
then the blog config file, then one of the posts.  In each case
\fw{mb} detected the change and ran its usual regeneration routine.

You can set the hostname and port that \mathblog\ uses to serve the
blog; see the \fw{mb -h} output.

\subsection{Blog 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, author, and date values go on the first
three lines of the file as follows:

\begin{verbatim}
% My First Post
% Author Name
% August 4, 1976

First paragraph starts here.
\end{verbatim}

Dates in the blog post header formatted as ``\fw{<MONTH> <DAY>,
  <YEAR>}'' will be parsed and used to generate the RSS feed
publication date.

\section{When Should I Run \fw{mb}?}

\fw{mb} looks at the modification times of the post files in
\fw{posts/}, the config file, template files, asset files, and the
posts index (see Section \ref{sec:postsindex}) when determining when
to regenerate content.  It also looks for new posts that haven't been
rendered in the past.  The rule of thumb is: re-run \fw{mb} whenever
you make any changes to anything in your blog data directory.

Modifications a post file will cause that post to be re-rendered, but
modifications the configuration file or templates will cause ALL posts
to be re-rendered since those changes impact how all pages are
generated.

\section{Customization}
\label{sec:customizing}

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 \fw{templates/} subdirectory of your blog data directory
and are as follows:

\begin{itemize}
\item{\fw{templates/rssTemplate.xml} - This is the template used to
  generate your RSS feed.}
\item{\fw{templates/pageTemplate.html} - This file makes up the
  overall structure of every page on the blog.}
\item{\fw{templates/postTemplate.html} - This file makes up the
  structure of the post portion of the page, for pages which show
  posts (i.e., not the posts index).}
\item{\fw{templates/listTemplate.html} - This file is the template
  used to generate the "all posts" page.  Once generated, the
  all-posts listing is then embedded in the page template.}
\end{itemize}

The templates mentioned above are ``StringTemplate'' templates and are
processed with the \fw{HStringTemplate} package.  The following
template placeholders are supported in each template:

\begin{itemize}
\item{\fw{\$title\$}, \fw{\$baseUrl\$}, \fw{\$authorName\$},
  \fw{\$authorEmail\$} - These placeholders all correspond directly to
  fields on the `blog.cfg` configuration file.}
\item{\fw{\$extraPageHead\$} - Content to be placed in the \fw{<HEAD>}
  tag of the page, such as javascript tags, stylesheets, etc.  You'll
  need to ensure that this is somewhere in your \fw{<HEAD>} tag if you
  want to use \mathblog\ features which may need to load extra
  resources.}
\end{itemize}

These placeholders are provided in the list template:

\begin{itemize}
\item{\fw{\$posts\$} - The list of all posts in the blog, starting with
  the most recent.  Each has the same structure as a post in the post
  template (i.e. post.title, post.date, post.url).}
\end{itemize}

These placeholders are supported in the post template:

\begin{itemize}
\item{\fw{\$next\_post\_url\$}, \fw{\$prev\_post\_url\$} - URLs to the
  next (newer) and previous (older) posts relative to the current
  post.  One or both may be null.}
\item{\fw{\$post\_html\$} - The rendered body of the post itself.}
\item{\fw{\$post.basename\$} - The base name of the post for use in
  Javascript (see Section \ref{sec:disqus} for an example).}
\item{\fw{\$post.title\$} - The title of the post as found in the Pandoc
  header.}
\item{\fw{\$post.date\$} - The publication date string of the post as
  found in the Pandoc header.}
\item{\fw{\$post\_authors\$} - The list of post author names as found in
  the Pandoc header.  This can be rendered as follows:
\begin{verbatim}
Posted by $post_authors; separator=", "$
\end{verbatim}
}
% tex-macros below just happens to hyphenate properly to prevent a long line,
% but keep an eye out: if the surrounding text changes enough, tex-macros may
% become (wrongly) texmacros due to the hyphenation hint.
\item{\fw{\$post.tex\_macros\$} - The combined \TeX\ macros string as
  found in all of the \fw{\#tex\-macros} code blocks in the post.  See
  the section on \TeX\ macros for how to use this properly.}
\end{itemize}

These placeholders are supported in the page template:

\begin{itemize}
\item{\fw{\$content\$} - The content of the page to be rendered.}
\end{itemize}

\section{Blog Assets}

The default blog directory created by \fw{mb} also includes an
\fw{assets/} subdirectory.  Whenever \fw{mb} detects changes in your
blog post or asset files (or if you run ``\fw{mb -f}''), everything in
\fw{assets/} will be copied recursively into the output directory.
This way, if you have custom stylesheets or other files which need to
be available, they can be kept in your data directory and published
with the rest of the generated content.

\section{\TeX\ Macros}

You can define post-wide \TeX\ macros and then reference them in both
Mathjax expressions and TikZ pictures.  To do this, define \TeX macros
inside a ``\fw{tex-macros}'' block as follows:

\begin{verbatim}
~~~ {#tex-macros}
\newcommand{\stuff}{...}
~~~
\end{verbatim}

The block will be removed from the document during preprocessing, but the
macros must be re-embedded in the final output HTML for Mathjax by updating
your post template to include this \textit{before} the post body:

\begin{verbatim}
<div style="display: none;">
\\(
$tex_macros$
\\)
</div>
\end{verbatim}

The \TeX\ macros will automatically be included in generated
\TeX\ source when TikZ processing is performed.  This way, you can
write macros and use them everywhere in the document without having to
redefine them inside picture environments.

\section{TikZ Embedding}

\mathblog\ supports inline scripts for rendering function graphs and
diagrams.  Right now, only the TikZ \LaTeX\ package is supported.  Set
the appropriate configuration option (see Section
\ref{sec:configuration}) to enable it.

To specify a TikZ diagram in a blog post, we overload the Pandoc code
block syntax.  Here's an example of a TikZ figure:

\begin{verbatim}
~~~ {#tikz}
\begin{axis}[
    minor tick num=3,
    axis y line=center,
    axis x line=middle,
    ]

\addplot[smooth,mark=none,blue] plot coordinates {
    (-1,-1)
    (2.95,2.95)
};
\end{axis}
~~~
\end{verbatim}

This is a \LaTeX\ fragment which will automatically be embedded in a
\fw{tikzpicture} environment and rendered to an image within the blog
post.  The fragment above will produce this picture:

\begin{tikzpicture}
\begin{axis}[
    minor tick num=3,
    axis y line=center,
    axis x line=middle,
    ]

\addplot[smooth,mark=none,blue] plot coordinates {
    (-1,-1)
    (2.95,2.95)
};
\end{axis}
\end{tikzpicture}

\subsection{Styling TikZ Graphics CSS}

Note that the Pandoc syntax also allows us to assign CSS class names
to the code block, and \mathblog\ passes these through to the generated
image.  So if you wanted to wrap your text around the generated image,
you could create a CSS class like this:

\begin{verbatim}
.eq-right {
  float: right;
}
\end{verbatim}

and then assign it to your equation graph like this:

\begin{verbatim}
~~~ {#eq-basic .eq-right}
...
~~~
\end{verbatim}

For more information on the code block syntax, please see:

\href{http://johnmacfarlane.net/pandoc/README.html\#fenced-code-blocks}{http://johnmacfarlane.net/pandoc/README.html\#fenced-code-blocks
}

\section{Disqus Integration}
\label{sec:disqus}

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 page basename
string so you can configure Disqus properly:

\begin{verbatim}
var disqus_identifier = "$post.basename$";
\end{verbatim}

\section{Controlling Post Order}
\label{sec:postsindex}

Whenever \fw{mb} detects that you have added a new post, it updates the ``posts
index'':

\begin{verbatim}
$MB_DATA_DIR/posts-index
\end{verbatim}

This file lists the filenames of all posts from newest to oldest.  By default,
new posts get added to the beginning of the list, as you would expect.  Any new
posts added to the list are sorted by modification time so that the newest post
on disk appears earlier in the index.  This feature exists to make it possible
for older posts to be updated without changing their ordering in the overall
sequence of posts.

You can edit the index at any time to reorder the posts as you see fit.
\fw{mb} will preserve ordering of posts already in the index when it runs.
\fw{mb} will also take care of removing posts from the index if they've been
removed from the post source directory.

\end{document}