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

content editing

writing math

To write mathematical equations and symbols we use asciimath which is a syntax similar to latex, but wherein the formulas themselves are quite readable before being rendedered.

Most mathematicians would know what you're saying if you wrote x^2 or a_(m n) or a_{m n} or (x+1)/y in an email, IRC or any other chat forum, in asciimath this renders as `x^2` or `a_(m n)` or `a_{m n}` or `(x + 1)/y`

To get started, enclose your math with single backticks and check the syntax to find the symbols you need.

adding figures/graphics

The general strategy is to always use scalable vector graphics 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 (such as a latex file if you're using tikz).

If you're curious about how you can create svgs yourself, then take a look at inkscape on desktop since it allows you to add latex code to your graphics. If you are working in the browser then check out svg-edit

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>
				

adding statements with proof

These are theorems, propositions, lemmas, corollaries, exercises

<div id="STATEMENT_TYPE-TODO">
	<div class="STATEMENT_TYPE" >
		<div class="title">TODO</div>
		<div class="content">
			TODO
		</div>
	</div>

	<div class="proof">
		<div class="title"></div>
		<div class="content">
			<details>
				<summary>show</summary>
				TODO
			</details>
		</div>
	</div>
</div>
				

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

<span class="knowledge-link" data-href="ABSOLUTE_PATH_TO_FILE_CONTAINING_KNOLWEDGE#KNOWLEDGE_ID">TODO</span>
				

The easiest way to understand this is by example:

<span class="knowledge-link" data-href="/number_theory/number_theory.html#definition-divides">divides</span>
				

adding new files

When creating new files, make sure that the name of the file is in lowercase snake_case, make sure to include the stylesheet /styles/style.css and the javascript /js/script.js and defer it's loading. Also wrap everything in the body with a thin-wrapper classed div

The path to the file should make logical sense and each level represent another level of detail/abstraction

update the main repository with your changes

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