MathCask is a quick starter kit for hosting your mathematical notes
and snippets as self-rendering, distributable HTML documents. 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:
-
Finally, click Commit changes, review/change the commit
message, and click Commit changes again. -
Wait for a few minutes for GitHub to publish your new HTML page.
Assuming you had named itfoo.html, now visit
https://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
