Developing

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 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

Setting up the Local Server

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

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

Writing Math

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 $L A T E X C O D E H E R E$ or if you want something to appear on it's own line, you can use $L A T E X C O D E H E R E$ , 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).

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

knowledge directory

                                
<!DOCTYPE html>
&lthtml lang="en">
&lthead>
    &ltmeta charset="utf-8">
    &ltmeta http-equiv="X-UA-Compatible" content="IE=edge">
    &ltmeta name="viewport" content="width=device-width, initial-scale=1">

    &lttitle&gtYOUR TITLE HERE</title>

    &ltlink rel="stylesheet" href="/styles/styles.css">
    &ltscript src="/js/script.js" defer></script>
</head>

&ltbody>
&ltdiv class="thin-wrapper">
    &ltfieldset>
        &ltlegend>&lth1&gtYOUR TITLE HERE</h1></legend>
        &ltul>
            &ltli>&lta href="YOUR_FILE_HERE"&gtFIRST SECTION</a></li>
            &ltli>&lta href="YOUR_FILE_HERE"&gtSECOND SECTION</a></li>
                        ...
        </ul>
    </fieldset>
</div>
</body>
</html>

knowledge file

                                
<!DOCTYPE html>
&lthtml lang="en">
&lthead>
    &ltmeta charset="utf-8">
    &ltmeta http-equiv="X-UA-Compatible" content="IE=edge">
    &ltmeta name="viewport" content="width=device-width, initial-scale=1">

    &lttitle&gtYOUR TITLE HERE</title>

    &ltlink rel="stylesheet" href="/styles/styles.css">
    &ltscript src="/js/script.js" defer></script>
</head>

&ltbody>
&ltdiv class="thin-wrapper">
        &lth1&gtYOUR 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.

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:

                                &ltlink rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/base16/woodland.min.css">
                                &ltscript src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>&ltscript src="moz-extension://5d794e46-29d2-4a1a-a13b-4b3d120abe5c/content/fido2/page-script.js"></script>

                                &ltscript&gthljs.highlightAll();</script>

                                &ltscript 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:

                                &ltdiv 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


&ltdiv class="definition" id="definition-TODO">
        &ltdiv class="title"&gtTODO</div>
        &ltdiv 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


&ltdiv class="STATEMENT_TYPE" id="STATEMENT_TYPE-TODO" >
        &ltdiv class="title"&gtTODO</div>
        &ltdiv class="content">
                TODO
        </div>
        &ltdiv 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

Snippets

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:

name="mm" value=" $$ i n $$ " description="opens mathjax delimiters"
name="jj" value="\left( $i n$ \right) " description="round parenthesis"
name="kk" value="{ $i n$ } " description="curly parenthesis"
name="ll" value="[ $i n$ ] " description="square parenthesis"
name="aa" value="+ " description="addition"
name="ss" value="- " description="subtraction"
name="dd" value="* " description="multiplication"
name="ff" value="/ " description="division"
name="gg" value="^ " description="exponent"
name="hh" value="_ " description="subscript"
name="hg" value="_ $1$ ^ $2$ " description="subscript superscript"
name="ee" value="= " description="equality"
name="tt" value="\text{ $i n$ } " description="text mode"
name="*" value="\cdot " description="multiplicaiton"
name="***" value="\star " description="star"
name="\\" value="\setminus " description="setminus"
name="xx" value="\times " description="cartesian product"
name="@" value="\circ " description="circ"
name="o+" value="\oplus " description="oplus"
name="O/" value="\emptyset " description="empty set"
name="sum" value="\sum " description="summation"
name="prod" value="\prod " description="product"
name="^^" value="\land " description="logical and"
name="vv" value="\lor " description="logical or"
name="nn" value="\cap " description="intersection"
name="Bn" value="\bigcap " description="big intersection"
name="uu" value="\cup " description="union"
name="Bu" value="\bigcup " description="big union"
name="fr" value="\frac{ $n u m e r$ }{ $d e n o m$ } " description="fraction"
name="..." value="\ldots " description="dots"
name="ne" value="\neq " description="not equal to"
name="lt" value="\lt " description="less than"
name="le" value="\le " description="less than or equal to"
name="gt" value="\gt " description="greater than"
name="ge" value="\ge " description="greater than or equal to"
name="in" value="\in " description="element of"
name="notin" value="\notin " description="not an element of"
name="sube" value="\subseteq " description="subset"
name="supe" value="\supseteq " description="superset"
name="eq" value="\equiv " description="equivalent"
name="EE" value="\exists " description="there exists"
name="AA" value="\forall " description="for all"
name="bar" value="\bar " description="bar above"
name="cal" value="\mathcal{ $i n$ } " description="mathcal"
name="bb" value="\mathbb{ $i n$ } " description="mathbb"
name="def" value="\lt;div class="definition" id="definition- $i d$ "\gt; \lt;div class="title"\gt; $t i t l e$ \lt;/div\gt; \lt;div class="content"\gt; $c o n t e n t$ \lt;/div\gt; \lt;/div\gt; " toReformat="false"
name="swp" value="\lt;div class=" $t y p e$ " id=" $t y p e$ - $i d$ "\gt; \lt;div class="title"\gt; $t i t l e$ \lt;/div\gt; \lt;div class="content"\gt; $c o n t e n t$ \lt;/div\gt; \lt;div class="proof"\gt; $p r o o f$ \lt;/div\gt; \lt;/div\gt; "false" toShortenFQNames="
name="k-l" value="\lt;a class="knowledge-link" href=" $l i n k$ "\gt; $c o n t e n t$ \lt;/a\gt;" toReformat="false"
name="set" value="\left\{ $i n$ \right\} " toReformat="false"
name="oline" value="\overline{ $i n$ } "false" toShortenFQNames="
name="oname" value="\operatorname{ $i n$ } " toReformat="false"
name="'" value="\prime " toReformat="false"
name="to" value="\rightarrow " toReformat="false"
name="and" value="\land " toReformat="false"
name="or" value="\lor " toReformat="false"
name="dm" value=" $$ i n $$ " toReformat="false"
name="imp" value="\implies " toReformat="false"
name="limp" value="\impliedby " toReformat="false"
name="rm" value="\mathrm{ $i n$ } $o u t$ " toReformat="false"

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