A CKAN extension providing the Mat-O-Lab theme for data portals. It includes configurable branding (logo, banner, favicon), GDPR-compliant privacy pages in English and German, and a customisable landing page suitable for materials science research data repositories. It works with both CKAN base themes, the default one and the opt-in midnight-blue theme (the default of CKAN 3.0).
Compatibility with core CKAN versions:
| CKAN version | Compatible? |
|---|---|
| 2.9 and earlier | not tested |
| 2.10 | ✓ CI tested |
| 2.11 | ✓ CI tested |
| 2.12 | ✓ CI tested |
To install the extension:
- Activate your CKAN virtual environment, for example:
. /usr/lib/ckan/default/bin/activate- Use pip to install package
pip install ckanext-matolabtheme-
Add
matolabthemeto theckan.pluginssetting in your CKAN config file (by default the config file is located at/etc/ckan/default/ckan.ini). -
Restart CKAN. For example, if you've deployed CKAN with Apache on Ubuntu:
sudo service apache2 reloadCKAN 2.12 ships an opt-in midnight-blue theme. Enable it in ckan.ini:
ckan.base_public_folder = public-midnight-blue
ckan.base_templates_folder = templates-midnight-blue(in Docker: CKANINI__CKAN__BASE_PUBLIC_FOLDER / CKANINI__CKAN__BASE_TEMPLATES_FOLDER). The plugin detects the active
theme (ckan.base_templates_folder) and loads matching styles:
| file | loaded | content |
|---|---|---|
style.css |
always | Mat-O-Lab branding: palette tokens, our own markup (landing page, footer, header navigation, dataset items) and, for generic components, only colours and backgrounds |
style-default.css |
default theme only | layout, typography and spacing fixes of generic components (forms, navigation, links, ...) that the default theme needs |
style-midnight.css |
midnight-blue only | maps midnight's hard-coded blue (links, buttons, form labels, active navigation, facet headers, pagination) to --bs-primary, readable text on the format badges and the counters, hover style of the light outline buttons, spacing of the sidebar and a sticky footer for short pages |
midnight-blue does layout and typography of the generic components itself (including its own font), so none of that is
overridden there. The optional dark mode (ckanext.matolabtheme.dark_mode) is only available on the default theme. The
landing page, footer, header navigation and dataset item templates are ours and keep the Mat-O-Lab layout on both themes.
The helper h.matolabtheme_is_midnight_blue() returns the active theme if you want to branch in your own templates.
Header (banner_top.svg) and footer (banner_bottom.svg) are crisp SVG files —
a teal gradient with flowing sinusoidal wave lines. Upload replacements or set
an external URL via Admin → Theme Config.
On first load the plugin seeds ckan.site_custom_css with a default navy CSS
variable palette (if no custom CSS is already configured):
:root {
--bs-primary: #1a3d5c;
--bs-primary-rgb: 26, 61, 92;
--bs-secondary: #4a7fa5;
--bs-secondary-rgb: 74, 127, 165;
--bs-body-bg: #f0f4f7;
--bs-body-bg-rgb: 240, 244, 247;
}The same tokens are also set in style.css, so the palette applies even when the custom CSS field is used for
something else. To customise colors go to Admin → Config → Custom CSS and override any CSS variable — no restart
required. Clearing the field restores the plugin defaults on the next restart. On midnight-blue, --bs-primary also
drives links, buttons, form labels, active navigation items and facet headers, so one variable recolours the whole site.
All options are read from ckan.ini or from environment variables with the CKANINI__ prefix
(ckanext.matolabtheme.contact_url becomes CKANINI__CKANEXT__MATOLABTHEME__CONTACT_URL):
| ckan.ini key | Default | Description |
|---|---|---|
ckanext.matolabtheme.contact_url |
https://github.com/Mat-O-Lab |
Target of the "Kontakt" button in the footer |
ckanext.matolabtheme.legal_notice_url |
/legal_notice.html |
Target of the "Impressum" button in the footer |
ckanext.matolabtheme.legal_person_md |
Legal body address (Markdown) for the privacy page | |
ckanext.matolabtheme.dsvgo_contact_md |
Contact for data protection conflicts (Markdown) | |
ckanext.matolabtheme.contact_dp_commissioner_email_md |
Data protection commissioner email (Markdown link) | |
ckanext.matolabtheme.dark_mode |
false |
Dark colour scheme (default theme only) |
ckanext.matolabtheme.banner_top / banner_bottom |
/static/banner_top.svg / /static/banner_bottom.svg |
Header and footer banner |
ckanext.matolabtheme.favicon |
/static/Logo.svg |
Favicon |
ckanext.matolabtheme.attribution_logo |
/static/Logo.svg |
"Provided by" logo in the footer |
Banners, favicon and attribution logo can also be uploaded in Admin → Theme Config. Example .env for Docker:
CKANINI__CKANEXT__MATOLABTHEME__CONTACT_URL=<url to contact site>
CKANINI__CKANEXT__MATOLABTHEME__LEGAL_PERSON_MD=<Legal Body Address in Markdown>
CKANINI__CKANEXT__MATOLABTHEME__LEGAL_NOTICE_URL=<Url to your legal notice information>
CKANINI__CKANEXT__MATOLABTHEME__DSVGO_CONTACT_MD=<Contact to adress with dsvgo conflicts in markdown>
CKANINI__CKANEXT__MATOLABTHEME__CONTACT_DP_COMMISSIONER_EMAIL_MD="[datenprotection_commissioner@example.de](mailto:datenschutzbeauftragte@example.de?subject=dataprotection ${CKAN_HOST})"
CKANINI__CKAN__SITE_LOGO=/static/Logo.svg
CKANINI__CKAN__FAVICON=/static/favicon.pngIf no contact_url is given, it will relate to the about page.
Use relative paths for logos and icons (/static/Logo.svg), not an absolute https://<host>/static/Logo.svg built
from the site URL. With an absolute URL the browser requests the image from another origin whenever you open the site
with a different scheme or hostname (for example http:// while the site URL is https://), which fails with a
self-signed certificate, so the header logo shows as a broken image.
To install ckanext-matolabtheme for development, activate your CKAN virtualenv and do:
git clone https://github.com/Mat-O-Lab/ckanext-matolabtheme.git
cd ckanext-matolabtheme
pip install -e ".[dev]"To run all tests (needs a CKAN test database, as in the CI workflow):
pytest --ckan-ini=test.ini ckanext/matolabthemeckanext/matolabtheme/tests/test_theme_split.py needs neither a database nor CKAN fixtures. It checks the split of the
stylesheets, the theme detection and the midnight-blue fixes, and can be run on its own:
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest ckanext/matolabtheme/tests/test_theme_split.pyIf you use this software, please cite it. GitHub shows a "Cite this repository" button (top right of the repo page) that exports the CITATION.cff in APA or BibTeX format.
After the first Zenodo release, a DOI-specific BibTeX entry will be available on the Zenodo record. Until then:
@software{hanke_ckanext_matolabtheme,
author = {Hanke, Thomas},
title = {ckanext-matolabtheme},
url = {https://github.com/Mat-O-Lab/ckanext-matolabtheme},
license = {AGPL-3.0-or-later},
}