The Sources of the OpenMath.org website
This website is hosted as a GitHub page. In short, it is built statically from Markdown source files using Jekyll. To update a page, just modify the corresponding source and push. This can be done online by clicking on "Edit this page" in the side bar. See the above links for details.
_config.yml: main configuration page
_post/*.md: sources of the news and blog posts
_data/*.yml: YAML database from which certain pages are automatically generated
_layouts/*: local style files
_includes/*: reusable chunks of web pages, like the side bar
public/*: Jekyll style files (almost vanilla), logos, ...
How to use Jekyll to test/build this website
These instructions are for OpenMath members who wish to do more than the occasional editing.
Editing pages online with GitHub
You can edit any page by following the "Edit this page" link in the
sidebar. Alternatively, you can directly navigate to the corresponding
.md (Markdown) file in GitHub.
This will drop you in GitHub's file editing interface, where you can modify the source code, preview it, and save your changes, by giving a short description of what you modified. If you have write access to the repository, your modifications will be published right away. If you do not have write access, you will be asked to fork the repository and make a pull request.
Imports from other OpenMath Repositories
Some of the content of the page is imported from other repositories:
symbols.md: are automatically pushed from the
masterbranch of the CDs repository by Travis on that repository.
standard, the newer versions (in particular the editor's draft) of the OpenMath 2 standard are pushed from from the
masterbranch of the OMSTD repository by Travis on that repository. The SCSCP standard is currently manually synchronized with the SCSCP repository.
The relative paths of these are chosen for backwards compatibility with older
versions of the OpenMath website. In particular,
cdfiles is a redirect
for the MathML Recommendation.
If you want to do more than the occasional editing, you'll soon realise GitHub's editor and preview are too limited. It's better to work locally on your computer.
At some point, you will need to preview your work, but pushing to GitHub each time you want to preview is clumsy. Your best option is to install Jekyll and the required dependencies on your machine. It is recommended to install the GitHub pages gem which provides you with the exact same versions used by GitHub to compile your site.
If you already have Ruby, the install part should be as easy as
gem install github-pages
Note that you will need Ruby headers (
ruby-dev package on Ubuntu) in
order to compile C dependencies.
Under macOS, you can just type
sudo gem install github-pages.
Now you can
cd into your local clone of the repository and launch
the compilation by
jekyll serve -w -b''
Your site will be generated in a
_site sub-directory, and served
live at http://localhost:4000/. Any changes to the sources will
trigger an automatic recompilation!