OpenAD Website

This repo holds the OpenAD website:

openad.accelerate.science

• Marketing page
• Documentation
• Blog / Tutorials

Development

Auto-generated content

Some of the documentation pages are automatically generated or updated by the generate_docs() script.
Jump to the /generator directory for details.

Development Server

Run the development server at localhost:8000

Note

No need to clone this repo
You can add or edit blog posts directly on GitHub and they will be published immediately.

# Create & activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Launch development server at :8000
mkdocs serve

# Optional: launch on custom port
mkdocs serve -a localhost:9999

Build Local

mkdocs build

Deployment

Deployment to GitHub pages happens automatically when changes are pushed to the main branch, via the ci.yml build workflow. Build progress can be followed under the GitHub Actions tab.

Hosting & Domain Name

This website is hosted on GitHub Pages at acceleratedscience.github.io/openad-website. Our domain is registered with Google domains and managed by the IBM webmaster, with a CNAME record pointing to acceleratedscience.github.io per GitHub docs.

Warning

There is a local CNAME file connecting the domain name to our GitHub pages website hardcoded in the /main folder. Usually this file is automatically added by GitHub Pages, but because our build process will rebuild the gh-pages branch every time, the GitHub-provided file gets erased with every update. Hardcoding the file circumvents that. More info.

---

Developer Notes

Stack

This is a heavily skinned version of the Material theme for MkDocs, which is a Python-based website generator that builds a website from markdown files.

We use the Material blog plugin for the blog functionality.

Architecture

• All content lives inside markdown files in the /main directory
• Navigation and all other site settings are controlled from mkdocs.yml
• The homepage as well as certain components use HTML overrides, more on which below
• The build is written to /site
• A GitHub workflow called ci.yml runs the build command and stores the build files into a branch called gh-pages, which is connected to our URL via GitHub Pages (see Hosting & Domain Name below)

HTML overrides

Overrides let us customize the HTML components that are used to render the site, by mirroring the Material templates inside the main/_overrides folder.

For components, we can simply override the original templates with our own version by mirroring them inside the /main/_overrides folder.

For full-page overrides (only used for the homepage), we can specify a custom template in the page metadata:

---
title: Home Page
template: home.html
---

In most cases we opted for cold hard CSS overrides (see main/_css) to maintain compatibility with MkDocs.

Documentation

• MkDocs documentation - The base framework
• Material documentation - Material is a theme for MkDocs with a bunch of additional functionality built in.