We store the website files on github, it's a way to track changes and allow others to contribute to the website. The openmath repository is the true version as to what you see online. If this repository were to be editable by anoyone without review then it would turn to pure chaos and malicious users could simply delete the entire site if they wanted to.
To deal with this github has something called a fork which allows you to take a github repository and make a copy under your ownership, this forked repository is editable by you in any way, but these changes do not affect the openmath repository. Assuming you've made non-malicious edits to your forked repository and you want to merge them into the openmath repository, you can create a pull request which is a request to merge in your changes.
When a maintainer on the openmath repository sees your pull request they will review it and if they think it looks good, they will merge your your work into the openmath, once that happens the website is rebuilt with the new update and should be live within minutes.
If it's your first time using github then an easy way to get started is to create a github account and download github desktop
While working on the project, we use fetch requests to load in content from local files like headers and knowledge from other webpages, so we have to set up a local server to let the fetch requests go through
An easy way if you have python is installed and run python -m http.server in the html folder to start up a webserver, you can then access this at localhost:8000
When using openmath you should notice two kinds of pages, there are pages that actually contain mathematical content, and pages that are purely there for organization, this mirrors the directory and file structure that you're already familiar with on your own computer. For our conventions we will call a page that lists other pages a knowledge directory, and one that contains content, a knowledge file.
The general rule of thumb is to have at most one or two screenfulls of content per knowledge file, but this is not a hard rule. A knowledge directory should on average contain 7 links to knowledge pages since it's been scientifically shown that your mind can usually only remember 7 things at once.
openmath is a static html site that uses vanilla js and css. Mathjax is used to render mathematical equations and for any animations/interactions we use three.js (a wrapper over webgl)
MathJax let's you embed latex code directly into your html files, to do this you just have to delimit in-line code like this \( LATEX CODE HERE \) or if you want something to appear on it's own line, you can use \[ LATEX CODE HERE \], if you're not yet familiar with latex, then
this post may help you get up to grips (note they use dollar signs instead of our delimiters).
When creating new files, make sure that the name of the file is in lowercase snake_case. The path to the file should make logical sense and each level should represent another level of detail/abstraction
When you need to create a new file, you're either creating a knowledge directory, or you're creating a knowledge file as mentioned in the organization section, here are templates for each:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>YOUR TITLE HERE</title>
<link rel="stylesheet" href="/styles/styles.css">
<script src="/js/script.js" defer></script>
</head>
<body>
<div class="thin-wrapper">
<fieldset>
<legend><h1>YOUR TITLE HERE</h1></legend>
<ul>
<li><a href="YOUR_FILE_HERE">FIRST SECTION</a></li>
<li><a href="YOUR_FILE_HERE">SECOND SECTION</a></li>
...
</ul>
</fieldset>
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>YOUR TITLE HERE</title>
<link rel="stylesheet" href="/styles/styles.css">
<script src="/js/script.js" defer></script>
</head>
<body>
<div class="thin-wrapper">
<h1>YOUR TITLE HERE</h1>
MATH_CONTENT_HERE
</div>
</body>
</html>
Note that in either case we've made sure to include the stylesheet /styles/style.css and the javascript /js/script.js and to defer it's loading. We've wrapped everything in the body with a thin-wrapper classed div to force the content closer to the center of the screen.
The general strategy is to always use scalable vector graphics when possible, this will allow any figures or graphics we include to be able to be scaled up without losing any quality of the graphic.
Additionally, we want to make sure graphics can be tweaked and edited by other users, so include any source files used to create the graphic.
If you're curious about how you can create svgs yourself, then take a look at at the following software.
Alternatively you can use latex directly with the tikz package using standalone and converting to svg, if done this way, include any conversion commands used.
If you aren't familiar with any svg tools, you may include rasterized graphics, in this case at least make sure you've given the graphic an alpha (see through) background.
As of right now if you'd like to include source files on a webpage, I recommend you add the following into the head of your document:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/base16/woodland.min.css"> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script><script src="moz-extension://5d794e46-29d2-4a1a-a13b-4b3d120abe5c/content/fido2/page-script.js"></script> <script>hljs.highlightAll();</script> <script src="/js/insert_file_contents.js"></script>
Here we're loading in our code highlight package, and also including the code which allows us to insert code file contents. Then wherever we want to include a file we do the following:
<div class="code-file" data-file-name="../implementation/breadth_first_search.cpp"></div>
The script automatically pulls the file extension and figures out how to highlight it.
A general template may be used like this
<div class="definition" id="definition-TODO">
<div class="title">TODO</div>
<div class="content">
TODO
</div>
</div>
definition- should be the title in lowercase, with any latex formatting removed and all spaces replaced with dashes.
point in \( \mathbb{R}^{n} \), then the id would be definition-point-in-Rn
These are theorems, propositions, lemmas, corollaries, exercises
<div class="STATEMENT_TYPE" id="STATEMENT_TYPE-TODO" >
<div class="title">TODO</div>
<div class="content">
TODO
</div>
<div class="proof">
TODO
</div>
</div>
A knowledge link allows you to have a clickable element which expands whatever it links to directly on the page. In general knowledge will be any definition or statement with proof
<a class="knowledge-link" data-href="ABSOLUTE_PATH_TO_FILE_CONTAINING_KNOLWEDGE#KNOWLEDGE_ID">TODO</a>
The easiest way to understand this is by example:
<a class="knowledge-link" data-href="/number_theory/division.html#definition-divides">divides</a>
Which generates this: divides
Once you've made your changes, then you can commit them and push them to your fork. Once you've pushed them you can create a pull request by going to the github page for your branch
Your changes will be live once once your pull request has been merged into the openmath repository (which is reviewed by hand) and after the github pages build process completes.
If you still don't see changes use control+shift+r to clear your browser cache and forces the browser to reload the most recent version of the current page
If you work with the project for a while you'll eventually wish you could do certain tasks quickly, in whatever editor you end up using I recommend creating snippets like these: