An MkDocs plugin to create shareable admonitions
Project description
Shareable Admonition Plugin for MkDocs
The Shareable Admonition Plugin is a custom extension for MkDocs, a static site generator geared towards project documentation. This plugin enhances the documentation by allowing the inclusion of shareable admonitions with embedded images and descriptions directly within your Markdown files.
Features
- Admonition with Images: Easily embed images within admonitions to make your documentation more engaging and informative.
- Customizable Admonitions: Supports MkDocs' native admonition syntax with the added capability to include images and custom text.
- Automatic Image and Text Extraction: Automatically extracts the first image and text from the admonition block for display.
Installation
To install the Shareable Admonition Plugin, you can use pip:
pip install shareable-admonition-plugin
Configuration
After installation, you need to activate the plugin in your mkdocs.yml configuration file:
Update mkdocs.yaml
plugins:
- search
- shareable_admonition
extra_javascript:
- javascripts/copy-link.js
google_tag: !ENV GOOGLE_ANALYTICS_KEY
Ensure that you also include any other plugins you wish to use.
Copy the css and javascript
Copy the docs/stylesheets/share-card.css
into stylesheets
folder in your docs directory.
Copy the docs/javascripts/copy-link.js
into javascripts
folder in your docs directory.
Usage
To use the plugin, simply include an admonition in your Markdown file as you normally would, but now you can also embed an image and a description, with the url note-slug
:
!!! note "This is a custom note" note-slug
![Image Alt Text](image_url.jpg)
This is a description that will be extracted along with the image.
The plugin supports the standard MkDocs admonition types (note, warning, tip, etc.) and allows for the inclusion of images either by using Markdown image syntax or HTML tags.
Development
This plugin is developed using Python and integrates with MkDocs through its plugin system. It uses regular expressions to parse admonitions and extract relevant information, and Jinja2 for templating.
Contributing
Contributions to the Shareable Admonition Plugin are welcome. Please feel free to submit pull requests or create issues for bugs and feature requests on the project's GitHub page.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_shareable_admonition-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 31a1c7d754503c47b0cd6e3629ac8d9ea6d8ca6109f9176f1a898213a5b407a0 |
|
MD5 | 237961a39a9aa036a4d1e5b282b615cc |
|
BLAKE2b-256 | 1e9a509986af271ddd4106aa81f057c824d6f34530ed294b3c0a72ece2d4ca5d |
Hashes for mkdocs_shareable_admonition-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 15f4d5643eafc547d7af2767952e3b6e5b6dfc4611600d79a858027620bad928 |
|
MD5 | 633c56dce9764822b48eaa90ea523f64 |
|
BLAKE2b-256 | a7a6c9b93519ac4effa74408c01642d04c71636faaafdfa51c8c00f22845301f |