Update details:

markdownmermaid is no longer maintained and should be replaced with mermaid2

• Project Name: markdownmermaid

Replace with mermaid2

Additional context:

The plugin is no longer maintained, and has bugs which means it no longer works.

• Add category
• Update category:

Category details:

• Category Title: Templates
• Category Subtitle:

Additional context:

It would be nice if one could add templates like e.g. https://github.com/geraldolsribeiro/microci_arc42 (arc42 documentation template).

Project details:

• Project Name:
• Github URL:
• Category:
• License:
• Package Managers:

Additional context:

Project details:

• Project Name: Risonia theme
• Github URL: https://github.com/unverbuggt/mkdocs-risonia-theme
• Category: theming
• License: MIT
• Package Managers: pypi:mkdocs-risonia-theme

Additional context:

A simple theme for MkDocs. Based on this demo using the w3.css framework and configurable color schemes (inspiration here).

Configuration Change:

theme: material
plugins:
  - info
  - offline
  - search
  - social
  - tags

The info plugin will always terminate the build, it is solely used for reproduction of issues. Also, the offline plugin should always be used with an environment variable, because it will switch off use_directory_urls and copy the search index to a JavaScript file.

Suggested change

theme: material
plugins:
  - search
  - social
  - tags

Possibly this page has lots of extension that we don't list here: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions.

Project details:

• Project Name: mkdocs-open-in-new-tab
• Github URL: https://github.com/JakubAndrysek/mkdocs-open-in-new-tab
• Category: links-refs
• License: MIT
• Package Managers: pypi_id: mkdocs-open-in-new-tab

Additional context:

This plugin adds JS code to open outgoing links and PDFs in a new tab.

The automatic opening of links in a new tab is a common feature of modern websites. It is also a good practice for accessibility. However, it is not a default behavior of Markdown. This plugin adds a JavaScript code to your website that opens external links and PDFs in a new tab.

Look at the demo.

Running pip install $(mkdocs get-deps) in a project that lists pymdownx.blocks.admonition, etc., gives the following warnings:

WARNING -  Extension 'pymdownx.blocks.admonition' is not provided by any registered project
WARNING -  Extension 'pymdownx.blocks.definition' is not provided by any registered project
WARNING -  Extension 'pymdownx.blocks.details' is not provided by any registered project
WARNING -  Extension 'pymdownx.blocks.html' is not provided by any registered project
WARNING -  Extension 'pymdownx.blocks.tab' is not provided by any registered project

I suppose we just have to add these extensions to pymdownx in our data.

I feel like it could be beneficial to setup a workflow that would automatically publish the readme file as a MkDocs-based site on GitHub.
The main benefit I could see here is the fact of a (probably) better search to find plugins, extensions, themes, etc. in it, which with current options (GitHub's repo search or simple Ctrl+F) is not as optimal I would say.

Tho, this is by no means something that has to be done here... Just an idea that could be considered.

Hi.
I'm thinking maybe to rename this repository from "best-of-mkdocs" to "catalog". That way:

• People will be less intimidated to add a project (we want all projects here, not just "best")

• I'm gonna be using it as a catalog from mkdocs/mkdocs#3205

No other change necessary other than renaming

Project details:

• Project Name: Family tree example
• Github URL: https://github.com/unverbuggt/mkdocs-familytree-example
• Category: integrations/template
• License: GPL3
• Package Managers: none (github repo)

Additional context:

An interactive family tree visualization using d3-dag

Wrapped in MkDocs, Risonia Theme, encryptcontent plugin and simple hooks.

Tree is gernerated from Gramps via import script.

Project details:
ldeluigi/markdown-docs is my GitHub Action powered by mkdocs and mkdocs-material to allow straightforward usage and integration of mkdocs with GitHub Actions.
The rationale is zero-configuration-needed, you specify a folder as source of markdown files and another folder as destination, and it works just fine like that. Optionally someone can use the same action with some customization.

The action also implies support of some markdown extensions (see readme), and is also published as a Docker image on Docker Hub so that it can be used in other CI providers.

• Project Name: markdown-docs
• Github URL: https://github.com/ldeluigi/markdown-docs
• Category: idk maybe a new one called something like "Automation Machinery" or Other
• License: MIT
• Package Managers: github-actions:ldeluigi/markdown-docs github-packages:ghcr.io/ldeluigi/markdown-docs dockerhub:deloo/markdown-docs

Additional context:
This action can be used in a minimal workflow even in this project, thus solving issue #174 with zero/minimal configuration:

See the usage example: https://github.com/marketplace/actions/markdown-docs#usage

Example:

name: GitHub Documentation

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  github-pages:
    name: Build and deploy documentation
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # To enable the git based extensions that lookup history
      - name: Build documentation 📚
        uses: ldeluigi/markdown-docs@v0
        with:
          src: .
          dst: ./gh-pages
          title: MkDocs Catalog
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./gh-pages
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Hi,
I'm the author of mkdocs-publisher project that contains multiple plugins. Some of them can be used separately, but some of them can work in cooperation. It's easier to test and maintain, especially when all of them are related to the one goal or personal web page/blog publishing. I want to add this project to this repository, but I'm not sure how to do it "the right way". Adding it as a mkdosc-publisher makes no sense, since there is no proper category for it. The close one is templates, since templates can contain multiple plugins, but it's not a template. The other idea is to add each of the plugins separately, but then I have to link all of them to the same repository, etc. If this is "the way" should I create a separate pull request or do a single one (it's described to do a one per plugin, but since it's a collection, should the same rule apply?). Please advise.

Hello,

I recently created a plugin for mkdocs, but it currently is hosted on gitlab: mkdocs-adresses. I was wondering if I had to transfer it to github to see it potentially added to the catalog of mkdocs plugins?

Regards,
Fred

Project details:

• Project Name: mkdocs-entangled
• Github URL: github.com/entangled/mkdocs-plugin
• Category: Code execution, variables & templating
• License: Apache 2
• Package Managers: pypi:mkdocs-entangled-plugin

Additional context:

Entangled is a solution for Literate Programming, a technique in which the programmer writes a human narrative first, then implementing the program in code blocks.

Literate programming was introduced by Donald Knuth in 1984 and has since then found several surges in popularity. One thing holding back the popularity of literate programming is the lack of maintainability under increasing program complexity. Entangled solves this issue by offering a two-way synchronisation mechanism. You can edit and debug your code as normal in your favourite IDE or text editor. Entangled will make sure that your Markdown files stay up-to-date with your code and vice-versa. Because Entangled works with Markdown, you can use it with most static document generators.

The mkdocs-entangled plugin integrates Entangled into MkDocs' event loop, and includes a module for building artifacts using snippets of makefiles.

Consider this:

I know that I have

- plugins:
    include-markdown

Now I just need to install whatever package contains that plugin.

I can easily find this in this config, because the name happens to match:

https://github.com/pawamoy/best-of-mkdocs/blob/6ca7c8801cfda1b422e225a74f391c8680289a97/projects.yaml#L811-L813

So then I know to pip install mkdocs-include-markdown-plugin.

But, can we ensure that this actually always matches?
Can we also distinguish between extensions and plugins? Maybe something like below - one of mkdocs_plugin and markdown_extension:

 - name: include-markdown 
   mkdocs_plugin: include-markdown
   github_id: mondeja/mkdocs-include-markdown-plugin 
   pypi_id: mkdocs-include-markdown-plugin 

Inspired by https://github.com/mkdocstrings/regressions/blob/master/plugin_map.yml 😉

For example, mkdocs-docskimmer is currently broken (does not work with latest MkDocs), and based on the author's answer it likely won't be fixed. So I wonder if we should simply remove it from the catalog, since it will only waste the time of users trying it.

Same goes for every other project listed in the catalog. I'm of course not asking that someone actually tries every project: we can simply act on a project when someone finds out it doesn't work with latest Markdown/MkDocs and isn't maintained.

Even better would be to run automated tests in CI:

• can the project be installed (no dependency conflict) alongside latest mkdocs/markdown?
• can the project be enabled in mkdocs.yml, as advertised, without errors?
• can the project be used without errors? This one is way more involved. We wouldn't check if things are "correctly" rendered (we leave that to the project's own tests), only if features can be used without hard errors.

Project details:

• Project Name: mkdocs-typer
• Github URL: https://github.com/bruce-szalwinski/mkdocs-typer
• Category: API Documentation Building
• License: Apache-2.0 license
• Package Managers: pypi:mkdocs-typer

Additional context: