📘 mkdocs-webis

Webis style and BibTeX citations for MkDocs Material.

This MkDocs plugin...

• ... styles your documentation like the Webis homepage (a dark gray navigation bar with the Webis logo, the "Product Sans" and "Noto Sans" fonts, plain headings, blue links and buttons, flat tables, and a light gray footer),
• ... lets you cite references from a BibTeX file with [@key] or [@key1, @key2], rendered as gray author–year citations like "[Fang et al., 2004]", and appends a list of the cited references (including their BibTeX) to each page.

The documentation is rendered with the plugin itself, so it doubles as a demo.

Installation

Install the package from PyPI:

pip install mkdocs-webis

Usage

Enable the plugin in your mkdocs.yml (together with the Material theme):

theme:
  name: material

plugins:
  - webis:
      # Optional: BibTeX file in your docs directory.
      bibliography: references.bib

Citations

With a bibliography configured, cite references by their BibTeX keys:

Axioms are formal constraints on retrieval models [@fang2004formal].
Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axiomatic].

Citations are rendered as gray author–year links in brackets (e.g., "[Fang et al., 2004]" or "[Hagen et al., 2016; Bondarenko et al., 2022]"), like on the Webis slides. They link to a "References" section at the bottom of the same page, which lists all references cited on that page. Multiple keys are separated by commas or semicolons. Citations also work in API docstrings rendered by mkdocstrings.

We recommend copying BibTeX entries from DBLP.

Style Elements

Besides styling the standard Material elements, the stylesheet provides a few CSS classes:

# Page Title

<p class="subtitle">A gray subtitle below the page title.</p>

<span class="badge">TFC1</span> — a small label, e.g., for names or acronyms.

The colors of webis.de are available as CSS variables (e.g., var(--webis-blue), var(--webis-red)) for your own stylesheets. See the style elements for how all elements look.

Development

To build this package and contribute to its development you need to install the build, setuptools and wheel packages:

pip install build setuptools wheel

(On most systems, these packages are already pre-installed.)

Development installation

Install package and test dependencies:

pip install -e .[tests]

Testing

Verify your changes against the test suite to verify.

ruff check .  # Code format, LINT, and security
mypy .        # Static typing
pytest .      # Unit tests

Please also add tests for your newly developed code.

Documentation and demo

The documentation in docs/ uses the plugin itself, including a page with all style elements and citations. Preview it locally to check changes to the style or the citations:

mkdocs serve

Build wheels

Wheels for this package can be built with:

python -m build

Support

If you have any problems using this package, please file an issue. We're happy to help!

License

This repository is released under the MIT license.