mathblog User`s Manual
Contents
1. e 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 The templates mentioned above are StringTemplate templates and are processed with the HStringTemplate package The following template placeholders are supported in each template CHAPTER 2 USING MATHBLOG 9 e StitleS SbaseUrl SauthorName SauthorEmail These placeholders all correspond directly to fields on the blog cfg configuration file e SextraPageHead Content to be placed in the lt HEAD gt tag of the page such as javascript tags stylesheets etc You ll need to ensure that this is somewhere in your lt HEAD gt tag if you want to use mathblog features which may need to load extra resources These placeholders are provided in the list template e SpostsS 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 These placeholders are supported in the post template e Snext_post_url prev_post_url1 URLs to the next newer and previous older posts relative to the current post One or both may be null e Spost_htm1 The rendered body of the post itself e Spost basename The base name of the post for use in Javascript see Section 2 9 for an example e Spost titles The title of the post as found in2. it to your equation graph like this eq basic eq right For more information on the code block syntax please see http johnmacfarlane net pandoc README html fenced code blocks 2 9 Disqus Integration 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 mat hblog makes this possible is by exposing a page basename string so you can configure Disqus properly var disqus_identifier post basenames 2 10 Controlling Post Order Whenever mb detects that you have added a new post it updates the posts index SMB_DATA_DIR posts index 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 CHAPTER 2 USING MATHBLOG 13 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 mb will preserve ordering of p
3. principles e A blog should be easy to create host and update e A blog should be easy to maintain CHAPTER 1 INTRODUCTION 3 e I should be able to edit posts in my editor of choice and write them in an intelligent textual markup language e It should be easy to embed high quality mathematical symbols and equations in the blog posts As a result mathblog has the following features e The sof tware is composed of a single executable which will automatically take care of creating your blog and regenerating pages when your blog post markup changes e 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 e mathblog s generated output files can be hosted by any web server e mathb log provides a built in web server for easy blog post authoring e Blog posts are written in the Markdown format with extensions as supported by the Pandoc document converter e Math is embedded with S or for inline math and S or for block level math These features have some nice advantages your blog content is cacheable and can be subjected to browser The revision control Posts are easy to edit and editing doesn t require a web static file representation model means you can compose a blog post on your laptop and get it just right using a local installation of mat hb1o
4. the Pandoc header e Spost date The publication date string of the post as found in the Pandoc header e Spost authors The list of post author names as found in the Pandoc header This can be rendered as follows Posted by Spost_authors separator e Spost tex_macros The combined TEX macros string as found in all of the tex macros code blocks in the post See the section on TEX macros for how to use this properly These placeholders are supported in the page template e Scontent The content of the page to be rendered CHAPTER 2 USING MATHBLOG 10 2 6 Blog Assets The default blog directory created by mb also includes an asset s subdirectory When ever mb detects changes in your blog post or asset files or if you run mb everything in 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 2 7 TEX Macros You can define post wide TEX macros and then reference them in both Mathjax expressions and TikZ pictures To do this define TfXmacros inside a tex macros block as follows tex macros newcommand stuff 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 befo
5. thor tle The title of your blog such as My math blog horName Your name for the RSS feed metadata and the page footer Email Your e mail address for the RSS feed metadata only thBackend The backend used to render TeX math expressions Right now the only possible value is mathjax No special configuration is necessary for MathJax as mathblog s default templates use CDN resources for MathJax CHAPTER 2 USING MATHBLOG 6 e tikz Whether to permit the use of the Tikz I4TgX package to create diagrams and function plots Set to yes on or 1 to enable Disabled by default All of the above fields can be accessed in templates using the syntax described in Section 2 5 below 2 3 Step 3 Edit Now you might want to edit or create a new post or remove one Start by editing the appropriate file in posts and then run mb To create a new blog post just create a new file ending in t xt in the post s subdirectory Here s an example of running mb after modifying an existing post S mb Rendering post first post Done Ordinarily you might run 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 mb by hand repeatedly you can run mb in listen mode in listen mode mb will start a lightweight web server and serve your blog locally while you edit it If you open a web browser
6. 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 CHAPTER 2 USING MATHBLOG 7 mb 1 Starring us im listen mocks so Done Blog generation complete Web server listening on http localhost 8000 File created blog posts posts index Rende ringi posc POs e mde ur Se POSEN Done mile mocliitaiecels Mlog nLogs alte Remcering post ComiEig 3s Elest poste Done mile moclifileels DlOG POSES test post exe Rendering post first post Done Above I ran mb in listen mode and then modified the posts index then the blog config file then one of the posts In each case 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 mb h output 2 3 1 Blog Post Format Posts are formatted in Markdown and support the extended Markdown syntax as imple mented 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 My First Post Author Name August 4 1976 A A Qe First paragraph starts here Dates in the blog post header formatted as lt MONTH gt lt DAY gt lt YEAR gt will be parsed and used to generate the RSS feed publication date CHAPTER 2 USING MATHBLOG 8 2 4 When Should I Run mb mb looks at the m
7. NG MATHBLOG 5 mb d blog o html i Tnitializing data directory blog Remcleirime POSte Si Done The directory structure of the new blog data directory is as follows e blog cfg The blog configuration file e posts e pos Blog post files x t xt ts posts index A special text file called the 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 2 10 e templates Templates used to generate the blog post pages post listing page and RSS feed These templates are StringTemplate templates e assets The directory where you can put arbitrary files to be copied to the HTML output directory mathblog will copy assets foo to MB_OUTPUT_DIR foo 2 2 Step 2 Configure mathblog creates a default INI style blog configuration file in your data directory called blog cfg It contains information which may be included in the generated pages The configuration file must have the following fields set e 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 eti e aut e au e ma
8. g 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 addi tion I m open to accepting contributions on the project if they re consistent with the goals I ve outlined above Happy blogging Chapter 2 Using mathblog The main program provided by the mathblog package is the program mb This program takes care of initializing new blog data directories detecting changes in your files regen erating the right HTML output files into your output directory and even serving them via HTTP while you work mb needs to know about two directories the data directory where your post input files and templates will be kept and the output directory where the HTML version of your blog will be generated mb has two ways of knowing about both of these directories you can set environment variables or you can pass command line flags to mb e Data directory set MB_LDATA_DIR in the environment or pass the d option to mb e Output directory set MB_OUTPUT_DIR in the environment or pass the o option to mb Any command line parameters given to mb will always take precedence over any environ ment variables 2 1 Step 1 Create Once you ve chosen your data and output directories run 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 CHAPTER 2 USI
9. mathblog User s Manual For mathblog version 0 5 Jonathan Daugherty cygnus foobox com October 3 2015 Contents 1 Introduction 2 LL Project Vision 62 04 cee cteeee tie ee at Pe eg See Eee s 2 2 Using mathblog 4 21 Dep COPR og ie ks ae a ee AAA EOS ee oe Bele Oe eds 4 22 EPA CN eca aid A dr ERA 5 2 Sep a Ed e e och aed Ree EES pk a ele eee eee wes 6 231 Blog Post Formal oce canes AAA AER be ee 7 24 When Should IRUN MD ca meee e ae e a ee ee a BS Se OHO 8 2 C USONANO si a la e a cs ee AA E AAA 8 20 PEOC AS ee a BRE A a E HE ESE 10 27 Vet Magn 2 fe wei eeu ewe debe ea hw ewe Ea a 10 28 TKZ Embedding o oc 6 ba es Be Ee ee IA ER Re A 10 28 1 Styling TikZ Graphics CSS correa rr ww Ew Oe A 11 29 DEUSTO AA 12 210 Controlling Post a A a a AA 12 Chapter 1 Introduction mathblogisa program targeted at people who want to write statically generated mathematically themed weblogs It supports e Extended Markdown input syntax as supported by the Pandoc library e Inline and block level TEX math rendered by MathJax e Function graphing and drawing with the TikZ BIEX package e Support for integration of Javascript based web services such as Disqus e Template based document rendering with support for layout and style customiza tion e A built in web server with automatic page reloading for easy blog post authoring 1 1 Project Vision I wrote mathblog with a very specific set of requirements in mind motivated by the following
10. odification times of the post files in post s the config file template files asset files and the posts index see Section 2 10 when determining when to regen erate content It also looks for new posts that haven t been rendered in the past The rule of thumb is re run 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 con figuration file or templates will cause ALL posts to be re rendered since those changes impact how all pages are generated 2 5 Customization 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 e templates rssTemplate xml This is the template used to generate your RSS feed e templates pageTemplate html This file makes up the overall structure of ev ery page on the blog e 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
11. osts already in the index when it runs mb will also take care of removing posts from the index if they ve been removed from the post source directory
12. re the post body lt div style display none gt et Stex_macros lt div gt The TEX macros will automatically be included in generated TEX source when TikZ pro cessing is performed This way you can write macros and use them everywhere in the document without having to redefine them inside picture environments 2 8 TikZ Embedding mathblog supports inline scripts for rendering function graphs and diagrams Right now only the TikZ IATFX package is supported Set the appropriate configuration option see Section 2 2 to enable it CHAPTER 2 USING MATHBLOG 11 To specify a TikZ diagram in a blog post we overload the Pandoc code block syntax Here s an example of a TikZ figure 777 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 y end axis This is a TEX fragment which will automatically be embedded in a tikzpicture envi ronment and rendered to an image within the blog post The fragment above will produce this picture A 2 8 1 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 CHAPTER 2 USING MATHBLOG 12 your text around the generated image you could create a CSS class like this eq right float right and then assign
Download Pdf Manuals
Related Search