Setup

To develop openmath locally you just need a terminal with python and git, along with an editor of your choice.

windows

install python
install git bash
install an editor, such as vscode

linux/mac

install python
install an editor

Getting the Files

We store the source files on github, I'm doing that because its probably the easiest way for us to get new contributors involved. If you don't know what github is, then read the following paragraph.

GitHub Intro

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 of what you see online. If this repository were editable by anyone without review, 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 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 work into openmath. Once that happens, the website is rebuilt with the new update and should be live within minutes.

Now that you have a github account, and understand what a fork is, you can navigate your way to openmath and then click the fork button to make your own fork. Once done you'll be at a page which is your version of the openmath site.

We want to get these files onto our comuter in a safe way so we will make sure that we have an ssh key attached to our github account before we make our next move.

how do I do that?

If you don't yet have a connected ssh key, then you just have to get yourself into a terminal and run ssh-keygen and hit enter through the prompts as the default values are fine (you can add a password if someone already broke onto your computer you might have bigger issues). After that you can type out cat ~/.ssh/id_ed25519.pub (alternatively there might be a id_rsa type key in there, but in either case just paste out the contents of the .pub file and copy to clipboard.

Then click your github profile and go to settings, then click the add ssh key section and paste the key in the key section and give the key a title such as the type of computer you're currenlty using (eg. desktop/laptop)

Now that we have an ssh key attached we can clone the files safely, so get back to your fork of openmath. Now open up a terminal and run the following

    
        git clone --recurse-submodules YOUR_SSH_URL_HERE

You can find your ssh url by clicking the green Code button on your github fork's website, then selecting the ssh tab, it will be of the form git@github.com:YOUR_GITHUB_USERNAME/openmath.git

Congratulations, you now have the openmath source code ready to go.

Developing

Now that you have the files you need to understand how openmath works. Openmath is a collection of html files, with content in them, the goal is to use html as much as possible as it renders better in the browser because browsers are designed for html, and whenever we require advanced mathematical formatting we use latex syntax. Since latex is not valid html code, we first need to turn all instances of latex code into valid mathml code which is how the browser renders math.

All that I'm trying to say here is that there is a sort of "compilation" phase that the files undergo to become valid html files, and because of this we need to run the continuous build script.

The continuous build script has some dependencies, and thus we need to install those first, here's how:

(run this from the root project directory)

    
cd scripts/precompiled_html_generation/
python -m venv generation_venv
source generation_venv/bin/activate
pip install -r requirements.txt 
./continuous_build.sh

The above installs the requirements and starts the continuous build script which will monitor the files and whenever you modify a file it will recompile just that file and update the site with that change. The newly compiled files will appear in the directory generated_html in the root project directory, these are the valid html files we talked about earlier.

Setting up the Local Server

You might think now that you can just explore the generated files directory directly, but that's still not the case.

why?

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

What we need to do is to use python to start a webserver in the generated_html directory. So navigate there and run python -m http.server, which starts up the webserver, then you just need to navigate to localhost:8000 in your browser. Now whenever you modify a file and save it, it will update in browser after a refresh.

In the future just remember whenever you want to start developing, you should do two things:

cd scripts/precompiled_html_generation/ and ./continuous_build.sh
cd generated_html and python -m http.server

Organization

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.

Content Editing

Creating new Files

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 index file, or you're creating a knowledge file as mentioned in the organization section, here are templates for each:

knowledge directory index file

index.html

    
<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>
        <!-- Add more list items as needed -->
    </ul>
</fieldset>

knowledge file

my_knowledge_thing.html

                                
<div class="definition" id="definition-title">
    <div class="title">
        TITLE
    </div>
    <div class="content">
        CONTENT
    </div>
</div>

You'll notice that these are not technically valid html files, but what would go between the body tags of an html page, as part of the compilation process they get converted to valid html files and other things are done to the pages such as adding a header to every page.

Another great way to learn about the format of these pages is to simply look at pre-existing pages.

Adding Figures/Graphics

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.

Adding Code Snippets

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.

Adding Definitions

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>

The mathematical content goes in place of the TODO between the content divs
The name/title of the definition goes between the title divs, for this use title case
The TODO after definition- should be the title in lowercase, with any latex formatting removed and all spaces replaced with dashes.

example
if the title was point in $ℝ^{n}$ , then the id would be definition-point-in-Rn

Adding Statements with Proof

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>

STATEMENT_TYPE should be replaced by one of theorem, proposition, lemma, corollary or exercise
for the TODO in the id, follow the same procedure for the definition
note that the id is stored in a div containing both the statement and the proof, this is so that if it is dynamically loaded elsewhere the proof will be visible as well.

Adding Knowledge Links

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


&lta class="knowledge-link" data-href="ABSOLUTE_PATH_TO_FILE_CONTAINING_KNOLWEDGE#KNOWLEDGE_ID"&gtTODO</a>

The easiest way to understand this is by example:


&lta class="knowledge-link" data-href="/number_theory/division.html#definition-divides"&gtdivides</a>

Which generates this: divides

Getting your Modifications on the Live Site

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

Check out the Changes

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

🏗️ ΘρϵηΠατπ🚧 (under construction)