Welcome to the repository for the website that holds the documentation of OpenEV Data. This site is built using MkDocs, a static site generator for displaying markdown documentation. If you're looking to make modifications or simply set it up locally, here's what you need to know.
- Python: 3.13+ is required https://www.python.org/
- Poetry: Used for consistent dependency management https://python-poetry.org/
-
Clone the Repository:
git clone https://github.com/open-ev-data/open-ev-data.github.io.git && cd open-ev-data.github.io
-
Install Dependencies:
poetry install
-
Serve the Website Locally:
poetry run mkdocs serve
This will start a local server, and you can access the site at
http://localhost:8000.
MkDocs uses Markdown for content. If you're new to Markdown, here's a quick guide.
If you want to add a new page, you can create a new markdown file in the /docs directory. To make the page visible in the navigation, add it in the mkdocs.yml file under the nav section. Take a look at the other markdown files for examples. Ideally add some frontmatter for at least the title to stay consistent.
We use the Material for MkDocs theme. In the file docs/assets/stylesheets/extra.css you can find all the customizations and add to them. This file basically overrides the default styling.
This site uses GitHub Actions to publish documentation versions. The deployment is triggered by pushing semantic version tags (e.g., v1.0.0).
When you push a tag with v*.*.* format:
git tag v1.0.0
git push origin v1.0.0The pipeline will:
- Extract the version (e.g., v1.0.0 → 1.0.x)
- Deploy documentation with that version
- Update the
latestalias - Set
latestas default
You can also trigger deployment manually from the GitHub Actions tab using the "workflow_dispatch" option.
The project uses mike for documentation versioning:
- Patch versions (v1.0.1, v1.0.2) map to the same minor version (1.0.x)
- Minor versions (v1.1.0, v1.2.0) create new documentation versions (1.1.x, 1.2.x)
- Latest alias always points to the most recent version
Example:
v1.0.0,v1.0.1,v1.0.2→ All deploy to version1.0.xv1.1.0→ Creates new version1.1.xv2.0.0→ Creates new version2.0.x
When the pipeline completes, view the documentation at https://open-ev-data.github.io
Open-source documentation for OpenEV Data - the single source of truth for electric vehicle specifications.
This documentation is licensed under CC-BY 4.0.