mkdocs-webis 0.1.0__py3-none-any.whl

docs/citations.md

@@ -0,0 +1,28 @@
+# Citations
+
+<p class="subtitle">Cite references from a BibTeX file by their keys.</p>
+
+With a `bibliography` configured, cite one or more references by their BibTeX keys:
+
+```markdown
+Axioms are formal constraints on retrieval models [@fang2004formal].
+Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axiomatic].
+```
+
+Which renders as:
+
+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, like on the Webis slides.
+Each links to the "References" section at the bottom of the same page, which lists all references cited on that page, sorted by first author.
+A journal article looks like this: [@fang2011diagnostic].
+
+## Details
+
+- Separate multiple keys by commas (semicolons work, too).
+- Citations inside inline code or code blocks are not replaced, as in the example above.
+- Unknown keys and invalid BibTeX files fail the build.
+- LaTeX markup in the BibTeX fields (e.g., `{\"{o}}` for "ö") is converted to plain text.
+
+We recommend copying BibTeX entries from [DBLP](https://dblp.org/).

docs/index.md

@@ -0,0 +1,42 @@
+---
+hide:
+  - navigation
+---
+
+# mkdocs-webis
+
+<p class="subtitle">Webis style and BibTeX citations for MkDocs Material.</p>
+
+This documentation is rendered with the plugin itself, so it doubles as a demo of the style.
+
+[Get started](#installation){ .md-button .md-button--primary }
+[View on GitHub](https://github.com/webis-de/mkdocs-webis){ .md-button }
+
+This MkDocs plugin...
+
+- ... styles your documentation like the [Webis homepage](https://webis.de/): 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, and appends a list of the cited references (including their BibTeX) to each page.
+
+## Installation
+
+Install the package from PyPI:
+
+```shell
+pip install mkdocs-webis
+```
+
+## Usage
+
+Enable the plugin in your `mkdocs.yml` (together with the [Material](https://squidfunk.github.io/mkdocs-material/) theme):
+
+```yaml
+theme:
+  name: material
+
+plugins:
+  - search
+  - webis:
+      bibliography: references.bib  # Optional: BibTeX file in your docs directory.
+```
+
+See the [style elements](style.md) for how Markdown elements look with this style.

docs/references.bib

@@ -0,0 +1,61 @@
+@inproceedings{fang2004formal,
+  author       = {Hui Fang and
+                  Tao Tao and
+                  ChengXiang Zhai},
+  title        = {A formal study of information retrieval heuristics},
+  booktitle    = {{SIGIR} 2004: Proceedings of the 27th Annual International {ACM} {SIGIR}
+                  Conference on Research and Development in Information Retrieval,
+                  Sheffield, UK, July 25-29, 2004},
+  pages        = {49--56},
+  publisher    = {{ACM}},
+  year         = {2004},
+  url          = {https://doi.org/10.1145/1008992.1009004},
+  doi          = {10.1145/1008992.1009004}
+}
+
+@article{fang2011diagnostic,
+  author       = {Hui Fang and
+                  Tao Tao and
+                  ChengXiang Zhai},
+  title        = {Diagnostic Evaluation of Information Retrieval Models},
+  journal      = {{ACM} Trans. Inf. Syst.},
+  volume       = {29},
+  number       = {2},
+  pages        = {7:1--7:42},
+  year         = {2011},
+  url          = {https://doi.org/10.1145/1961209.1961210},
+  doi          = {10.1145/1961209.1961210}
+}
+
+@inproceedings{hagen2016axiomatic,
+  author       = {Matthias Hagen and
+                  Michael V{\"{o}}lske and
+                  Steve G{\"{o}}ring and
+                  Benno Stein},
+  title        = {Axiomatic Result Re-Ranking},
+  booktitle    = {Proceedings of the 25th {ACM} International Conference on Information
+                  and Knowledge Management, {CIKM} 2016, Indianapolis, IN, USA, October
+                  24-28, 2016},
+  pages        = {721--730},
+  publisher    = {{ACM}},
+  year         = {2016},
+  url          = {https://doi.org/10.1145/2983323.2983704},
+  doi          = {10.1145/2983323.2983704}
+}
+
+@inproceedings{bondarenko2022axiomatic,
+  author       = {Alexander Bondarenko and
+                  Maik Fr{\"{o}}be and
+                  Jan Heinrich Reimer and
+                  Benno Stein and
+                  Michael V{\"{o}}lske and
+                  Matthias Hagen},
+  title        = {Axiomatic Retrieval Experimentation with ir{\_}axioms},
+  booktitle    = {{SIGIR} '22: The 45th International {ACM} {SIGIR} Conference on Research
+                  and Development in Information Retrieval, Madrid, Spain, July 11-15, 2022},
+  pages        = {3131--3140},
+  publisher    = {{ACM}},
+  year         = {2022},
+  url          = {https://doi.org/10.1145/3477495.3531743},
+  doi          = {10.1145/3477495.3531743}
+}

docs/style.md

@@ -0,0 +1,110 @@
+# Style Elements
+
+<p class="subtitle">How Markdown and Material elements look in the Webis style.</p>
+
+Use this page to check the style locally (`mkdocs serve`) when changing the stylesheet.
+
+## Text
+
+Regular text with **bold**, _italic_, `inline code`, [a link](https://webis.de/), and ==highlighted== text.
+Keyboard keys look like <kbd>Ctrl</kbd> + <kbd>C</kbd>.
+
+> A block quote, e.g., for a definition or a quotation.
+
+### Third-Level Heading
+
+#### Fourth-Level Heading
+
+Term
+:   A definition list entry.
+
+## Lists
+
+- An unordered list item
+- Another item
+    - A nested item
+    - Another nested item
+
+And an ordered list:
+
+1. An ordered list item
+2. Another item
+
+## Tables
+
+| Corpus | Publisher | Year | Documents |
+|:--|:--|--:|--:|
+| Webis-Query-Log | Webis | 2023 | 356,000,000 |
+| ClueWeb22 | CMU | 2022 | 10,000,000,000 |
+| MS MARCO | Microsoft | 2016 | 8,841,823 |
+
+## Code
+
+```python
+from mkdocs_webis import parse_bibtex
+
+# Parse a BibTeX file and print short citations.
+entries = parse_bibtex(open("references.bib").read())
+for key, entry in entries.items():
+    print(f"{key}: {entry.short_citation}")
+```
+
+## Admonitions
+
+!!! note
+    A note, e.g., for additional information.
+
+!!! tip
+    A tip, e.g., for best practices.
+
+!!! warning
+    A warning, e.g., for common pitfalls.
+
+!!! danger
+    A danger notice, e.g., for destructive operations.
+
+!!! example
+    An example.
+
+??? quote "A collapsible quote"
+    Collapsed by default.
+
+## Tabs
+
+=== "pip"
+
+    ```shell
+    pip install mkdocs-webis
+    ```
+
+=== "uv"
+
+    ```shell
+    uv add mkdocs-webis
+    ```
+
+## Buttons, Badges, and Cards
+
+[Primary button](#){ .md-button .md-button--primary }
+[Default button](#){ .md-button }
+
+<span class="badge">TFC1</span> — a small label, e.g., for names or acronyms.
+
+<div class="grid cards" markdown>
+
+- **Card one** — a short description.
+- **Card two** — another short description.
+
+</div>
+
+## Custom Classes
+
+The stylesheet provides a few CSS classes:
+
+```markdown
+<p class="subtitle">A gray subtitle below a 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.

mkdocs_webis/__init__.py

@@ -0,0 +1,11 @@
+from mkdocs_webis.bibliography import Bibliography, BibliographyError, Entry, parse_bibtex
+from mkdocs_webis.plugin import WebisPlugin, WebisPluginConfig
+
+__all__ = [
+    "Bibliography",
+    "BibliographyError",
+    "Entry",
+    "parse_bibtex",
+    "WebisPlugin",
+    "WebisPluginConfig",
+]