Show when page was already visited ("mark as read")

[ojacques]

👋 community!

I would like to be able to mark pages that I visited as read with an icon (such as fa-solid fa-check) next to the page in the table of content. Essentially a similar experience to the hugo theme "relearn".

Use cases would be:

• As a reader, I come back to the tutorial or workshop documentation few hours or days later after I started, and would like to resume back where I left.
• As a reader, I want to make sure I went through all the sections of the documentation to have a complete view of the service or product
• As a reader, I want to be able to reset pages I visited with a click of a button or hyperlink.

After some research, I saw an approach which would set a cookie - which makes me wonder how this could be done extending the theme.

Anyone has done this before? Worth a feature request maybe?

[squidfunk]

Thanks for suggesting. Where should this be stored persistently? Material for MkDocs spits out a static site, there's no storage except for local or session storage which we could use, but which is not necessarily persistent. Thus, if you come back later to the site, your marks may be gone. Can you find out how relearn does it?

[ojacques]

For the use cases above, it should be client side. The approach in the link suggests leveraging cookies, possibly with an expiration (for example 7 days).
Session storage would work too.

Looking at ReLearn, they use session storage (see code).

Another use case I see for mkdocs: when you look for something across the pages (which you cannot find with search because you don't know the term), it would show you all pages which you visited.

[squidfunk]

When it should be client side, it can (and must) be implemented in pure JavaScript. You could extract all links from the navigation, and check if the current URL matches the link. If it does, add it to a data structure in local storage. When rendering the page, annotate all links that have already been visited. Personally, I think this is of limited use, so I don't think we will add this to master.

[squidfunk]

... also, a much simpler approach is to use the browsers :visited state information and add appropriate styling.

[ojacques]

... also, a much simpler approach is to use the browsers :visited state information and add appropriate styling.

Thanks for the suggestion. I am no CSS wizard, but it looks feasible as just an extra CSS for this one mkdocs repository for tutorials.

If I proceed and succeed, I will update this thread.

Thanks!

[berk-karaal]

Good news everyone!
I also needed such a feature and after some tinkering I was convinced that the localStorage solution was viable, so I developed a plugin for the mkdocs-material theme. 🎉

@ojacques I didn't like the method in the "relearn" theme you shared, because the fact that I entered the page doesn't mean that I read it. For this reason, I added a "Mark as read" button at the end of each page where the plugin is activated, and when the user presses this button, the page is considered read.

Another feature of the plugin is that when the user enters the site, if a page that was previously marked as "read" has been updated, the material-update icon will be displayed next to that page in the navigation tab instead of the material-check icon (until the user marks the page as read again).

You can try the plugin on the documentation site: https://berk-karaal.github.io/mkdocs-material-mark-as-read/

Plugin is ready to use, you can follow the quickstart page to implement this plugin to your site. If you have any idea or found a bug please let me know :)

@squidfunk I'm looking forward for your comments about the plugin 🙂. Thanks for this beautiful project ❤️

[squidfunk]

Nice work! Really happy to see more plugins built on top of Material for MkDocs ☺️

[ojacques]

Very nice! I also like the configuration options you have included right from the start. I will definitely leverage your plugin.