sass/custom/_styles.scss
.]]>amsthm
package allows you to define environments for theorems, proofs, lemmas, definitions, and so on. However, MathJax doesn’t implement these higher-level formatting features. And rightly so; any formatting on the web should be done with CSS.
Looking to see if anyone has attacked this problem, I came across Samuel Coskey’s post where he suggests using custom HTML tags as a solution. However, it seems to be a bad idea to use custom HTML tags. A more robust solution would be to use custom CSS classes instead.
The CSS I’m using is in theorems.css
below. If you prefer an open Halmos / QED symbol versus the closed symbol, use \25FB
in place of \25FC
.
.theorem { display: block; margin: 12px 0; font-style: italic; }
.theorem:before { content: "Theorem."; font-weight: bold; font-style: normal; }
.lemma { display: block; margin: 12px 0; font-style: italic; }
.lemma:before { content: "Lemma."; font-weight: bold; font-style: normal; }
.proof { display: block; margin: 12px 0; font-style: normal; }
.proof:before { content: "Proof."; font-style: italic; }
.proof:after { content: "\25FC"; float:right; }
.definition { display: block; margin: 12px 0; font-style: normal; }
.definition:before { content: "Definition."; font-weight: bold; font-style: normal; }
|
If you happen to be using Octopress, which uses Sass, this code can be appended to /sass/custom/_styles.scss
.
And now to see this in action. The markdown (with inline HTML)
<div class="definition"> A set $C$ is *convex* if for all $x,y \in C$ and for all $\alpha \in [0,1]$ the point $\alpha x + (1-\alpha) y \in C$. </div>
<div class="theorem"> There are no natural numbers $\naturals = (1, 2, 3, \ldots)$ $x$, $y$, and $z$ such that $x^n + y^n = z^n$, in which $n$ is a natural number greater than 2. </div>
|
will produce the following:
One improvement would be to allow theorem names and numbering (with subsequent referencing), but I think for now this is a nice solution.
]]>It was fairly easy to setup, first simply install citeproc-ruby
and bibtex-ruby
gems by running
gem install citeproc-ruby
gem install bibtex-ruby
in the terminal, then add them to your Gemfile
by adding the two lines:
gem 'bibtex-ruby'
gem 'citeproc-ruby'
then you should be set to use them with Octopress. To configure, I grabbed the IEEE format from the citation style language repository and placed it in plugins/ieee.csl
, then I added these lines to _config.yml
:
# BibTex Citation plugin
citation:
citation_style: plugins/ieee.csl
citation_locale: en
I was getting an error when using citation.rb
, and it seems the issue was that it was reading the data as a string and not an array, and hence the .join
method was failing. So on Line 31 in citation.rb
I simply changed
#content = super.join
content = super
And now it works, no troubles. For instance the example
B. Brothman, Orders of value: probing the theoretical terms of Archival Practice
, Archivaria, vol. 32, no. 1, 1991.
was generated using
{% bibtex %}
@article{brothman1991orders,
title={Orders of value: probing the theoretical terms of Archival Practice},
author={Brothman, B.},
journal={Archivaria},
volume={32},
number={1},
year={1991}
}
{% endbibtex %}
Although it seems that to make a longer list I need to enclose each item in it’s own liquid block. So for now, it’s not the greatest solution.
]]>\text{}
command), the typeface would not match the surrounding content. If you like the MathJax typeface, the easiest way to solve this subtle problem is to use the MathJax typeface for your content.
In Octopress, this is fairly straightforward to do, thanks to this post, the bit of CSS one needs is
@font-face {
font-family: 'MJX_Main';
src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/eot/MathJax_Main-Regular.eot'); /* IE9 Compat Modes */
src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/eot/MathJax_Main-Regular.eot?iefix') format('eot'),
url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Regular.woff') format('woff'),
url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Regular.otf') format('opentype'),
url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/svg/MathJax_Main-Regular.svg#MathJax_Main-Regular') format('svg');
}
Since Octopress uses Sass, this is best placed in /sass/custom/_styles.scss
. I simply appended the code to the end. This defines a font-family MJX_Main
, which we can use for our serif styling by adding
$serif: "MJX_Main", serif;
to /sass/custom/_fonts.scss
.
So now the typeface used in this post will match that used in equations. For example, when I define \(\ind{A}\) as the binary indicator function of the event \(A\): \[ \ind{A} = \cases{ 1 & if $A$ is true,\cr 0 & otherwise,} \] the “otherwise’’ here is the same as in the equation. This makes the math a bit more seamless. It seems that going the opposite direction (styling MathJax to match your content) may be a bit more difficult.
]]>They have a few more videos on their website. Their rendition of AC/DC’s TNT is embedded below. Get headbanging, meatbags.
]]>There’s two parts here. The first is getting Octopress to work nicely with MathJax. This is relatively easy. Octopress has a folder for custom html files. On my install, it’s located at
/source/_includes/custom/
In this folder, find the head.html
file, and append the following:
<!--- MathJax Configuration -->
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML,https://drz.ac/javascripts/MathJaxLocal.js">
</script>
This does two things, first it loads MathJax from the MathJax CDN, then loads my custom preferences, which includes a whole slew of macros. My custom preferences are placed in the javascript folder,
/source/javascript/
notice that I need to specify the path to my local configuration in head.html
, and also at the end of the MathJaxLocal.js
script itself:
MathJax.Ajax.loadComplete("https://drz.ac/javascripts/MathJaxLocal.js");
With all this, I should now be able to write some beautiful mathematics, and the result should be rendered with MathJax: \[ F(\omega) = \int_{-\infty}^\infty f(t) e^{-i \omega t} \d t. \]
Some may be content with this. However, there were a few other things that troubled me, such as some errors that I would get due to the Markdown processing and the ability to preview my content offline.
In order to render your Markdown file as HTML, you need a Markdown interpreter. There are several options, rdiscount, kramdown, maruku, multimarkdown, and pandoc are ones that I’ve tried. Out of the box, Octopress can be easily configured to use either rdiscount, kramdown, or maruku. Being resistant to change, my goal was to be able to write equations exactly how I would in LaTeX. That is, by using the dollar sign characters for inline equations, and double dollar signs for display equations. This is specified in the MathJaxLocal.js
file. Initially it seemed that maruku handled the interplay with MathJax the best. However, oftentimes things would break. Often if I had an underscore in a math equation, markdown would think the text should be italicized, since that’s part of the markdown spec. At the end of this section, I have a test case which would oftentimes not be converted correctly.
As it turns out, pandoc is a more robust solution for interpreting markdown with mathjax syntax. However, Octopress is not configured to use pandoc out of the box. The first step is to install the latest version of pandoc. Next, we need to figure out how to use pandoc with Octopress. Thanks to this jekyll plugin, I was able to get started. Simply place this plugin in your plugins
directory. The pdf generation wasn’t working correctly for me, so I simply stripped out that portion of the code. So my pandoc.rb
reads
require 'open3'
module Jekyll
# Just return html5
class MarkdownConverter
def convert(content)
flags = @config['pandoc']['flags']
output = ''
Open3::popen3("pandoc -t html5 #{flags}") do |stdin, stdout, stderr|
stdin.puts content
stdin.close
output = stdout.read.strip
end
output
end
end
end
Then I needed to change my _config.yml
as follows:
markdown: pandoc
pandoc:
skip: false
flags: '--smart --mathjax'
now using the same rake commands, the markdown files are processed by pandoc. One interesting feature about pandoc, that I may discuss in the future, is that it supports the use of bibliographies using BibTeX.
This is a test case of markdown / MathJax weirdness.
Example: \(y = [z > 0]\).
Example:
If I have one integral here: \[ \int_{-\infty}^\infty f(x) \d x, \] and a second integral here \[ \int_{-\infty}^\infty g(t) \d t, \] we may introduce an issue.
Hopefully everything is displayed as it should!
With an internet connection, I can use the Octopress preview web host to check out how my draft is progressing. However, once an internet connection is unavailable, the MathJax typesetting breaks since it is essentially loading the configuration I’ve deployed to render the content I’m previewing. That is, the localhost server loads the MathJax configuration that’s actually located at https://drz.ac/javascripts/MathJaxLocal.js
. So once I don’t have wifi available, it can’t find this page, and my maths break.
My ideal solution would be to write my posts in a text editor then preview them offline without requiring the overly complex local webserver. While it’s great to see how things look before deploying a post, it can be distracting to deal with when I’m just trying to get my ideas down.
Enter Marked, a companion app for previewing Markdown content. Marked looks for changes in your markdown file, upon a change, converts it to HTML, and displays it in a nice preview window. By default, marked uses multimarkdown. Unfortunately, I would encounter similar issues with MathJax equations that I felt that I should just configure Marked to use pandoc instead. This is aided by using a small bash script as a wrapper for pandoc.
#!/bin/bash
# Wrapper for using pandoc with Marked
cat - | pandoc -S -f markdown -t html --mathjax
Simply use this script (making sure to chmod a+x
) as the custom markdown processor in the Marked preferences, and everything should work great. Now to get the equation support, I downloaded the latest version of MathJax and simply keep it in my Dropbox folder (~/Dropbox/MathJax/
). Within this MathJax folder, I also keep a copy of my MathJaxLocal.js
script, however one needs to change the last line to
MathJax.Ajax.loadComplete("file:///users/zac/Dropbox/MathJax/MathJaxLocal.js");
with the appropriate changes for your install. Then when I’m writing offline, I simply include my local MathJax install within the markdown file itself.
<script type="text/javascript"
src="file:///users/zac/Dropbox/MathJax/
MathJax.js?config=TeX-AMS-MML_HTMLorMML,
file:///users/zac/Dropbox/MathJax/MathJaxLocal.js">
</script>
So far, works great!
For now I’m going to stick with this solution. The only drawback is that I seem to need to always include the javascript to use my local MathJax configuration. It’s a little inelegant to have to include it every time, but that’s not too much of a headache. On the plus side I now have
My Octopress blog configured to use MathJax,
I can seemingly write nearly identically in style to standard LaTeX, and
Offline composing is made simple by using Marked.
The toilet’s flush produces a brief but traumatizing sound, a kind of held high-B gargle, as of some gastric disturbance on a cosmic scale. Along with this sound comes a suction so awesomely powerful that it’s both scary and strangely comforting: your waste seems less removed than hurled from you, and with a velocity that lets you feel as though the waste is going to end up someplace so far away that it will have become an abstraction, a kind of existential sewage-treatment system.
Harper’s has other articles by David Foster Wallace available online.
]]>The strange thing was that Firefox displayed everything correctly, but Google Reader and hence Reeder simply showed ⓩ
in place of the correct unicode symbol. As it turns out, the feed is encoded as utf-8
, however GitHub Pages was serving the file as US-ASCII
, causing the issue.
Thanks to Taylor Fausak’s post on serving atom feeds at GitHub, I was able to come up with a solution. Simply using the extension .atom
will make GitHub serve the correct headers. Rather than use the redundant atom.atom
, I elected to shoot for feed.atom
. To do this in Octopress was fairly straightforward.
In _config.yml
, I changed subscribe_rss: /atom.xml
to subscribe_rss: /feed.atom
. I thought this would be enough. I was wrong.
In the Rakefile
, plugins/category_generator.rb
, and sitemap_generator.rb
, search and replace atom.xml
with feed.atom
. (Strange these guys are hard coded).
In the source
directory, rename atom.xml
to feed.atom
.
Now I have a W3C certified valid feed and everything works splendidly. That is, until I break something new.
]]>2.1
branch of Octopress. From what I can tell, there’s an error in source/_includes/feed_entry.xml
.
To get the standard_post_marker
to function correctly a la Gruber, where it shows up before the title of his post in the RSS feed, I needed to do some digging.
To fix, I think all that you need to do is switch
{% if linklog and site.linklog_marker_position_feed == 'before' %}
{% unless linklog %}{{ site.standard_post_marker_feed }}{% endunless %}
to
{% unless linklog %}{{ site.standard_post_marker}}{% endunless %}
{% if linklog and site.linklog_marker_position_feed == 'before' %}
or else the 2nd line in the original can never execute.
I opened up an issue on the Octopress GitHub repository. Yay for OSS!
]]>It took me a little while to get this feature working in Octopress, as this post on GitHub seems a bit outdated. Thanks to Neal Sheeran for his post suggesting to use the 2.1
branch instead of the linklog-test
branch. After pulling that branch and merging conflicts I was able to get things working properly.
A last note, there are some configuration options for changing the style of the linked list posts. At some point I’ll have to decide on what side of the Gruber/Armet line I fall. For now I’ll stick with the defaults.
]]>Rakefiles are the Ruby equivalent of Makefiles. As detailed on the Octopress site, the Rakefile that ships with Octopress has a number of useful scripts (rake tasks) for generating new posts and deploying your site.
Generating a new post is as simple as
rake new_post["title"]
which creates a new Markdown file in your source/_posts
directory with filename given by the title, prepended by the date. This will already contain useful metadata that Octopress uses (see the YAML front matter section below). Simply edit this Markdown file to fill your post with content.
I haven’t added any new pages quite yet, but there is a rake task for creating new pages easily:
rake new_page[filename]
This will create the file source/filename/index.markdown
that will ultimately be served as filename/index.html
on your website.
To use a local webserver to serve all your posts (including ones with the published: false
flag), simply run
rake preview
and point your browser to http://localhost:4000
. One trick that made using this server a bit easier is to use Fluid to create an Octopress Preview
app. Note that to get MathJax (the subject of a future post) working correctly, I needed to change the User Agent to Safari, otherwise it didn’t seem that it handled JavaScript correctly.
If you’re satisifed with your site, you can generate the html files and deploy it to GitHub Pages by running
rake generate
rake deploy
Very slick.
Lastly, the beauty of having your site as the master
branch, and everything else as the source
branch is that you can modify your website and use version control without having to publish all your changes. Once you’ve made a new post or page, or some other tweaks to your page source, simply run
git add .
git commit -m 'your message'
git push origin source
and your progress will be saved on GitHub.
The special YAML Ain’t Markup Language front matter tells Octopress how to process your Markdown files. The new_post
script generates this for you. By default the published:
line is omitted. Including published: false
will prevent the post from being deployed, but will show when you preview your site locally with rake preview
. This is useful if you like to preview your post in a browser before deploying.
If you want to restrict the amount of a post that is shown in your blog index, simply insert the
<!-- more -->
tag into your post. The remainder of the post will not be shown in the blog index.
The plugins
directory contains some usful scripts. Here I’ll show a few examples.
Standard Markdown blockquotes, coded as
> Don't Panic.
> **Douglas Adams** - The Hitchhiker's Guide to the Galaxy
appears as
Don’t Panic.
Douglas Adams - The Hitchhiker’s Guide to the Galaxy
which is perfectly fine. However, using the blockquote
script, they appear a bit more fancy:
Don’t Panic.
This was created using
<blockquote><p>Don't Panic.</p><footer><strong>Douglas Adams</strong> <cite>The Hitchhiker's Guide to the Galaxy</cite></footer></blockquote>
This environment is especially nice for linking to quotes in articles. See the documentation for usage details.
Thanks to Xi Wang’s post about internal post linking, I was able to use his linked post_url
script to more easily make internal links to posts in this blog. Simply download post_url.rb and place it into your plugins
directory.
I used this code at the beginning of the post to generate the URL:
/2012/12/19/blogging-with-octopress/
Here 2012-12-19-blogging-with-octopress
is the name of the Markdown file (sans extension, of course) that I used to generate the previous post. Full disclosure, I used the Markdown syntax:
[Last time][BloggingWithOctopress]
[BloggingWithOctopress]: /2012/12/19/blogging-with-octopress/ "Blogging With Octopress"
]]>A blogging framework for hackersit immediately appealed to me.
Admittedly, I’m still qutie a neophyte when it comes to assemlbing websites, but I think this is a good list of some of the benefits of Octopress:
Static site deployment.
This is great because it reduces strain on your server, it just needs to serve up static websites, maybe with some plugins for displaying twitter information, but much less heavy than a Wordpress style site where blog posts are stored in a database and the html is generated dynamically.
Blog posts are stored as text files.
Maybe, at some unspecified date in the future, I want to migrate my entire website to a different blogging platform. This is easy to do if all the content is simply contained in ASCII text files. Further, any markup is facilitated by using Markdown. This makes my content extremely portable and future-proof.
Easy to work with GitHub Pages.
I just discovered this recently, but GitHub essentially lets you host a website that is simply a special repository. In my case, I have a github repo named zharmany.github.com. GitHub provides you the subdomain corresponding to your repo name, so my site can be accessed at zharmany.github.com. Publishing changes to the site simply entails pushing the my changes to github via git.
The remainder of this post details how to get started using Octopress with GitHub Pages.
This was fairly straightforward. I simply created a repository named harmany.github.com
. Since I’m a bit new to using GitHub, I used the web interface. If want to quickly fill your site with a template just to make sure things are working, GitHub provides an automatic page generator. You can alsays
The first task is to ensure that you have git and Ruby installed. I had a little trouble getting Ruby configured. I was following the Ruby setup instructions on the Octopress site, but had some difficulty installing 1.9.3-p0
. So I double checked the latest version number on the Ruby site, for example the version I installed was 1.9.3-p327
. As a result, I needed to also run
rbenv global 1.9.3-p327
for Ruby to be installed correctly.
Then I followed the rest of the Octopress install instructions, with the slight modification to the .rbenv-version
file to work with version 1.9.3-p327
that I had installed.
Next, I followed the instructions on configuring Octopress, and deploying to GitHub Pages.
Essentially what’s going on is that there will be two branches of your GitHub Pages site. The source
branch will contain all of your raw posts, Ruby scripts, etc. The master
branch is what gets served on the webpage.
I’ll go into a bit more detail on actually blogging with Octopress in the future, but if everything is setup correctly, you should be able to make some changes to your site and use Ruby scripts to generate your content and deploy the changes to GitHub Pages. This is simply done via
rake generate
rake deploy
and you should see your changes uploaded to your site.
Neat.
If you want to use a TLD instead of your default GitHub Pages URL, simply follow these instructions.
]]>