materialx-bookmarks

A bookmark list component for mkdocs-materialx. Write your links in YAML, drop one fence into any page, and readers get search, tag filtering, sorting and pagination — no JavaScript to write, no database, no build step of your own.

🔖 Try the live demo →

Search for a typo'd name, stack two tag filters, flip the order, page through — then copy the address bar and see the whole view come back.

Light	Dark

Why

Documentation sites accumulate link lists. Written as plain Markdown they turn into a wall of bullets nobody can search, and keeping them tidy means editing prose. This plugin keeps the data in YAML and the presentation in the theme:

Quick start

1. Install

pip install materialx-bookmarks

2. Write some bookmarks

Create bookmarks/reading.yml next to your mkdocs.yml:

tags:
  - python
  - rust

bookmarks:
  - title: Ruff
    description: Linter and formatter for Python, written in Rust.
    tags: [python, rust]
    links:
      - text: Docs
        url: https://docs.astral.sh/ruff/
      - text: GitHub
        url: https://github.com/astral-sh/ruff

  - title: ripgrep
    description: Recursively searches directories for a regex pattern.
    tags: [rust]
    links:
      - url: https://github.com/BurntSushi/ripgrep

3. Register the collection

plugins:
  - materialx-bookmarks:
      collections:
        - name: reading
          file: bookmarks/reading.yml

4. Drop it on a page

# My reading list

Things worth coming back to.

```bookmarks
collection: reading
```

That's it. mkdocs serve, and editing the YAML live-reloads the page.

Reference

Bookmark files

tags: [python, rust]        # allowlist — a bookmark may only use tags listed here

bookmarks:
  - title: Ruff             # the only required field
    description: …          # optional
    tags: [python]          # optional
    links:                  # optional — each entry needs a url
      - text: Docs          # optional — without it the button shows the hostname
        url: https://…

Bookmarks appear in the order you write them. The tags allowlist is what turns a misspelled tag into a build error instead of a chip nobody ever clicks.

Links render as buttons under the description, in the order you write them. A bookmark with no links renders as plain text.

Plugin options

plugins:
  - materialx-bookmarks:
      language: en
      collections:
        - name: reading
          file: bookmarks/reading.yml
          per_page: 20

Naming what a collection holds

By default the interface says "bookmarks" — "Search bookmarks", "3 of 12 bookmarks". A collection that holds something else can say so:

collections:
  - name: projects
    file: bookmarks/projects.yml
    item_name: project
    item_name_plural: projects

The nouns go into every string that needs one: Search projects, No projects found, 3 of 12 projects, and 1 of 1 project when a single entry matches. Give both keys or neither — the plugin will not guess a plural. Leave them out and each language supplies its own word, so a Turkish site reads "Yer işaretleri içinde ara" without any configuration.

Ordering the tag chips

collections:
  - name: tools
    file: bookmarks/tools.yml
    tag_sorting: count

Display modes

Bookmarks can be drawn three ways, and the reader picks between them from a switcher beside the search box:

collections:
  - name: tools
    file: bookmarks/tools.yml
    display: blocks
    block_min_width: 14rem

blocks	compact

display is where a collection starts. Set display_options to narrow what the reader may choose, or to [] to fix the mode and hide the switcher entirely:

    display: blocks
    display_options: [list, blocks]

The reader's choice is remembered in localStorage, namespaced by component id, so two collections on one page each keep their own. It is deliberately not in the URL: the display mode says how a collection is drawn, not which bookmarks it shows.

Letting readers choose the page size

collections:
  - name: tools
    file: bookmarks/tools.yml
    per_page: 12
    per_page_options: [12, 24, all]

A picker appears at the end of the count line. all drops pagination for that view. The list must include per_page, which stays the default. Without per_page_options nothing changes: the page size is yours alone.

Unlike the display mode, the page size is in the URL — it decides which bookmarks a given page number lands on, so a shared link would otherwise point somewhere else for the person who opens it.

Placing components

A page may hold as many components as you like. Give a fence an id when two of them would otherwise collide:

```bookmarks
collection: reading
id: reading-secondary
```

URL state

Every control that changes which bookmarks are shown writes to the address bar, namespaced by component id, so a filtered view can be linked to and returns intact:

?reading.q=ruff&reading.tags=python,rust&reading.sort=reversed&reading.page=2&reading.size=50

The display mode is the one exception, and lives in localStorage instead — see Display modes.

How it works

At build time the plugin reads your YAML, validates it, and writes one JSON file per collection into the site. Each fence becomes an empty container carrying its configuration. Anything wrong — a missing file, a bookmark without a title, a tag outside the allowlist, a fence naming a collection that does not exist — stops the build with a message naming the file and the entry.

In the browser a small bundle (about 30 KB including Fuse.js) fetches that JSON once per collection and renders the list. Assets are emitted under content-hashed filenames, so upgrading the plugin never leaves a visitor on a stale bundle.

Controls are real buttons with aria-pressed, the search box is labelled, the result count is a live region, and pagination sits in a landmark nav — all of it keyboard reachable.

Languages

English (en) and Turkish (tr) ship with the plugin, and the language follows your theme.language unless you set one. Adding another is a single file — see CONTRIBUTING.md.

Requirements

Python 3.10+, MkDocs 1.5+, and the mkdocs-materialx theme.

Contributing

Tests, the demo site and the release workflow are described in CONTRIBUTING.md.

License

MIT