MathCask is a quick starter kit for hosting your mathematical notes and snippets as self-rendering HTML documents that can be distributed easily. It supports Markdown and MathJax-flavored LaTeX, making it easy to write and distribute mathematical content.
You can use MathCask in multiple ways, depending on your technical background. If you're familiar with Git, GitHub, or Codeberg, you can set up a convenient workflow for yourself where you commit your notes into a Git repo and make them available online via GitHub pages or Codeberg pages. Alternatively, you can also host this kit on your personal web server or web hosting space.
If you're not familiar with these tools, don't worry. The first few sections below provide a gentle guide to help you get started.
- Set Up MathCask Using GitHub Pages
- Set Up MathCask Using Codeberg Pages
- Host On Your Own Web Server
- How Does This Work?
- Why?
- License
The subsections below describe how you can fork this project on
GitHub, and then write and maintain mathematical notes with it.
Naturally, this means that you need a GitHub account to perform these
steps. If you do not want to create an account on GitHub, skip ahead
to the other sections and see if one of them suits your needs better.
In this section the word USERNAME is used as a placeholder for your
GitHub username. Wherever you see this word, you must replace it with
your actual username.
The following steps describe how you can fork this project on GitHub, and then write and maintain mathematical notes with it:
-
Fork this project on GitHub by going to https://github.com/susam/mathcask and clicking the Fork button at the top.
-
Go to your forked copy of this project on GitHub and click Settings.
-
In the left sidebar click Pages.
-
Under the Branch section, click on the dropdown, select main, and click Save.
-
Wait for a few minutes to allow GitHub to deploy the pages in this kit using GitHub Pages.
-
Visit
https://USERNAME.github.io/mathcask/demo.html. Remember to replaceUSERNAMEin this URL with your actual username. Confirm the page loads fine on your web browser and all mathematical content is rendered properly. The output should look like this: demo.html -
You are now setup to use MathCask.
The following steps offer beginner-friendly instructions for creating a new page to host your mathematics notes or snippets written in Markdown and LaTeX. If you're an experienced Git user, you may prefer using the Git CLI tool to create and publish your pages instead of following these steps. However, if you're new to Git, you might the instructions below helpful.
-
Go to your fork of MathCask, which is likely at
https://github.com/USERNAME/mathcask. -
Click on Add file and then click Create new file.
-
Name your new file
foo.html. In fact, you could choose any name you like as long it has the extension.html. -
Now enter the following file contents:
<!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/[email protected]"></script><textarea> # Euler's Identity In mathematics, **Euler's identity** is the equality $$ e^{i \pi} + 1 = 0. $$ ## Explanation Euler's identity is a special case of Euler's formula from complex analysis, which states that for any real number $ x $, $$ e^{ix} = \cos x + i \sin x. $$
-
Finally, click Commit changes, edit the commit message if you like, and click Commit changes again.
-
Wait for a few minutes for GitHub to publish your new HTML page. Assuming you had named it
foo.html, now visithttps://USERNAME.github.io/mathcask/foo.htmland confirm the rendered page loads on your web browser. The output should look like this: example.html.
Codeberg.org is a project repository hosting platform provided by Codeberg e.V., a non-profit organisation. Codeberg also offers a service called Codeberg Pages that may be used to make your mathematical notes available as web pages. The subsections below describe how you can fork this project on Codeberg, and then write and maintain mathematical notes with it.
In this section the word USERNAME is used as a placeholder for your
GitHub username. Wherever you see this word, you must replace it with
your actual username.
The following steps describe how you can fork this project on GitHub, and then write and maintain mathematical notes with it:
-
Fork this project on CodeBerg by going to https://codeberg.org/susam/mathcask and clicking the Fork button at the top.
-
Visit
https://USERNAME.codeberg.page/mathcask/demo.html. Remember to replaceUSERNAMEin this URL with your actual username. Confirm the page loads fine on your web browser and all mathematical content is rendered properly. The output should look like this: demo.html -
You are now setup to use MathCask.
The following steps offer beginner-friendly instructions for creating a new page to host your mathematics notes or snippets written in Markdown and LaTeX. If you're an experienced Git user, you may prefer using the Git CLI tool to create and publish your pages instead of following these steps. However, if you're new to Git, you might the instructions below helpful.
-
Go to your fork of MathCask, which is likely at
https://codeberg.org/USERNAME/mathcask. -
Click on Add file and then click New file.
-
Name your new file
foo.html. In fact, you could choose any name you like as long it has the extension.html. -
Now enter the following file contents:
<!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/[email protected]"></script><textarea> # Euler's Identity In mathematics, **Euler's identity** is the equality $$ e^{i \pi} + 1 = 0. $$ ## Explanation Euler's identity is a special case of Euler's formula from complex analysis, which states that for any real number $ x $, $$ e^{ix} = \cos x + i \sin x. $$
-
Click Commit changes.
-
Wait for a few minutes for GitHub to publish your new HTML page. Assuming you had named it
foo.html, now visithttps://USERNAME.codeberg.page/mathcask/foo.htmland confirm the rendered page loads on your web browser. The output should look like this: example.html.
You can also host self-rendering Markdown + LaTeX pages on your own web server. In fact, you do not even need this project to do so. All you need to do is add HTML files that contain a simple boilerplate header to load TeXMe followed by Markdown + LaTeX content. Here is an example such HTML:
<!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/[email protected]"></script><textarea>
# Euler's Identity
In mathematics, **Euler's identity** is the equality
$$ e^{i \pi} + 1 = 0. $$
## Explanation
Euler's identity is a special case of Euler's formula from complex
analysis, which states that for any real number $ x $,
$$ e^{ix} = \cos x + i \sin x. $$The first line of this file loads TeXMe. The TeXMe parser parses the remainder of the file and renders the Markdown and MathJax-flavoured LaTeX in it. To learn more about TeXMe, see github.com/susam/texme.
If you have looked at the HTML examples from earlier sections, you may have noticed that they all begin with this line:
<!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/[email protected]"></script><textarea>This line loads TeXMe, a lightweight tool that can seamless render content written in a mixture of Markdown and MathJax-flavored LaTeX within the same HTML file. TeXMe processes the remainder of the HTML file and invokes a Markdown parser and a LaTeX renderer separately, ensuring that each parser only interprets the content meant for it. This prevents conflicts and produces clean, high-quality output.
One important feature of TeXMe is its conformance to the GitHub Flavoured Markdown (GFM) specification. Since GFM is an extension of the CommonMark specification, TeXMe also conforms to the CommonMark specification as a bonus. To achieve this, TeXMe invokes a high quality Markdown parser called Marked that is known for parsing and rendering GFM text accurately. To render MathJax-flavoured LaTeX, TeXMe invokes MathJax of course, ensuring accurate mathematical typesetting. To read more about TeXMe, visit github.com/susam/texme.
This quick starter kit was created as a substitute for MathB.in, a mathematics pastebin that operated from March 2012 to March 2025. After 13 years of service, MathB.in was shut down. See the post MathB.in Is Shutting Down for more details on why it was shut down.
MathB.in offered a very convenient way to quickly write down a short mathematical snippet or post using Markdown and LaTeX and then generate a distributable link for it with the click of a button. This service was powered by MathB, a free and open source software available at github.com/susam/mathb.
Users appreciated MathB.in for its ease of use and robust support for GitHub Flavoured Markdown (GFM) and MathJax-powered LaTeX. Since GFM is a strict superset of CommonMark, the parsing and rendering of user posts conformed to the CommonMark specification as well.
With the discontinuation of MathB.in, an alternative was needed. While this kit is nowhere near as quick and convenient as MathB.in, it does offer a reasonably easy way to set up your own little web space for sharing your mathematical snippets and notes. As mentioned in the previous section, this kit guides you through creating HTML pages for your snippets and notes that are automatically rendered using the TeXMe parser, the same parser used by MathB.in. This ensures that the parsing accuracy, rendering quality, and Markdown compatibility remain just as reliable.
Moreover, by structuring your documents this way, you retain full control over your documents and you can host them anywhere you like,
If you are very familiar with web technologies and hosting websites, you likely do not need this kit. In that case, you might want to take a look at TeXMe and start writing mathematical documents directly with it.
This quick starter kit is available under the terms of the MIT License.