Quickstart¶

This guide will help you to add mark as read feature to your mkdocs-material project.

1. Install Plugin¶

First install the plugin with pip install mkdocs-material-mark-as-read

Then add plugin to mkdocs.yml:

mkdocs.yml

plugins:
  - mark-as-read

This plugin uses attr_list and pymdownx.emoji markdown extensions so make sure they are enabled:

mkdocs.yml

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Set site_url config

If your website is not hosted on the root of the domain, you must set site_url in mkdocs.yml. Example for GitHub Pages:

mkdocs.yml

site_url: https://username.github.io/repo-name

2. Add "Mark as read" Button to Pages¶

To show a button at the end of the pages you should extend content.html template. Follow these steps:

Add custom_dir: overrides under theme in mkdocs.yml:
mkdocs.yml
```
theme:
  name: material
  custom_dir: overrides
```
Create overrides/ directory in the root of the project

Create overrides/partials/mark-as-read-button.html and copy paste the following content:

overrides/partials/mark-as-read-button.html

{% if page.meta and "mark_as_read" in page.meta %}
    <link rel="stylesheet" href="{{config.site_url}}css/mark-as-read-button.css">
    <button class="mark-as-read-button" onclick="markAsReadButtonOnClick()"></button>
    <script src="{{config.site_url}}js/mark-as-read-button.js"></script>
{% endif %}

This template will show "Mark as Read" button if page is configured to use mark as read feature. You can also customize this button easily, check out here.

Copy content.html file from mkdocs-material to overrides/partials folder and add highlighted line to it:

Since you are overriding content.html template, you should keep it up to date with the original one when mkdocs-material updates.

overrides/partials/content.html

{% if "material/tags" in config.plugins and tags %}
{% include "partials/tags.html" %}
{% endif %}
{% include "partials/actions.html" %}
{% if "\x3ch1" not in page.content %}
<h1>{{ page.title | d(config.site_name, true)}}</h1>
{% endif %}
{{ page.content }}
{% include "partials/source-file.html" %}
{% include "partials/feedback.html" %}

{% include "partials/mark-as-read-button.html" %}

{% include "partials/comments.html" %}

3. Use Plugin on Pages¶

Add mark_as_read meta to the pages you want users to be able to mark as read. You can add this meta to the top of the page like this:

---
mark_as_read:
    updated_at: 2024-03-24 17:00:00+03:00
---

# Page title

Your wonderful content

You should set updated_at field in date or datetime format. This field is used to inform user if the page is updated after the user marked it as read.

Tip: Setting up for lots of pages

If you already have lots of pages and don't want to add this meta to each of them, you can set regexes to activate plugin on pages. Check out include and exclude docs.

Congratulations, plugin is all set! Now you should see "Mark as read" button at the end of the pages.