Skip to content

Mkdocs‐Macros Pluglets

Laurent Franceschetti edited this page Feb 21, 2024 · 2 revisions

Introduction

Purpose

This page contains a list of available pluglets for Mkdocs-Macros.

What are pluglets?

A pluglet is a preinstalled module for mkdocs-macros, which is installed thanks to Pythons standard packaging process.

You can use pre-developed pluglets for MkDocs macros, or develop your own ones to:

  1. Extend the variables, functions and filters offered by MkDocs-Macros, in the Markdown pages.
  2. Extend the functionality of MkDocs, e.g. by providing headers, footers to each Markdown page.
  3. Replace MkDocs plugins that would otherwise conflict with MkDocs-Macros (because the syntax of those plugins would conflict with that of the templating engine)

Installation

Pluglets can generally be installed with pip, e.g. :

  • Pypi: pip install mkdocs-macros-test
  • Github: pip install git+https://github.com/fralau/mkdocs-macros-test.git

They must then be declared in the configuration file (mkdocs.yaml), e.g.:

plugins:
  - search
  - macros:
      modules: ['mkdocs_test`] 

How to announce a new pluglet?

Make an announcement in the discussions of MkDocs-Macros.

List

  1. Macro-Test: a test pluglet for mkdocs-macros. Its purpose is to serve as a template for pluglets (Github).
  2. Includex: include anything from any file into your markdown documentation (PyPI, Github).
  3. File-Include: defines a macro to include file contents using jinja2 template (PyPI, GitHub).
  4. Crystals: Mkdocstrings-Crystal is used to insert an API documentation into Markdown pages (generated from Crystal's source code and doc comments) as part of any Markdown page; this project provides a macro that can be used to dynamically generate Markdown based on the introspection of Crystal's type tree.(Documentation, Github).
Clone this wiki locally