# 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:
```bash
pip install shareable-admonition-plugin
```
## Configuration
After installation, you need to activate the plugin in your mkdocs.yml configuration file:
### Update mkdocs.yaml
```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`:
```markdown
!!! note "This is a custom note" note-slug
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 <img> 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/ianderrington/mkdocs-shareable-admonition",
"name": "mkdocs-shareable-admonition",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "mkdocs, python, markdown",
"author": "Your Name",
"author_email": "Ian Derrington <ian.derrington@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1e/9a/509986af271ddd4106aa81f057c824d6f34530ed294b3c0a72ece2d4ca5d/mkdocs_shareable_admonition-0.1.1.tar.gz",
"platform": null,
"description": "# Shareable Admonition Plugin for MkDocs\n\nThe 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.\n\n## Features\n* Admonition with Images: Easily embed images within admonitions to make your documentation more engaging and informative.\n* Customizable Admonitions: Supports MkDocs' native admonition syntax with the added capability to include images and custom text.\n* Automatic Image and Text Extraction: Automatically extracts the first image and text from the admonition block for display.\n\n## Installation\n\nTo install the Shareable Admonition Plugin, you can use pip:\n\n```bash\npip install shareable-admonition-plugin\n```\n\n## Configuration\nAfter installation, you need to activate the plugin in your mkdocs.yml configuration file:\n\n### Update mkdocs.yaml\n\n```yaml\nplugins:\n - search\n - shareable_admonition\n\nextra_javascript:\n - javascripts/copy-link.js\n\ngoogle_tag: !ENV GOOGLE_ANALYTICS_KEY\n```\n\nEnsure that you also include any other plugins you wish to use.\n\n### Copy the css and javascript \n\nCopy the `docs/stylesheets/share-card.css` into `stylesheets` folder in your docs directory.\nCopy the `docs/javascripts/copy-link.js` into `javascripts` folder in your docs directory. \n\n## Usage\nTo 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`:\n\n```markdown\n!!! note \"This is a custom note\" note-slug\n \n This is a description that will be extracted along with the image.\n```\n\nThe 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 <img> tags.\n\n## Development\nThis 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.\n\n## Contributing\nContributions 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.\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MkDocs plugin to create shareable admonitions",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/ianderrington/mkdocs-shareable-admonition"
},
"split_keywords": [
"mkdocs",
" python",
" markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a7a6c9b93519ac4effa74408c01642d04c71636faaafdfa51c8c00f22845301f",
"md5": "633c56dce9764822b48eaa90ea523f64",
"sha256": "15f4d5643eafc547d7af2767952e3b6e5b6dfc4611600d79a858027620bad928"
},
"downloads": -1,
"filename": "mkdocs_shareable_admonition-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "633c56dce9764822b48eaa90ea523f64",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 3683,
"upload_time": "2024-07-21T22:25:01",
"upload_time_iso_8601": "2024-07-21T22:25:01.978869Z",
"url": "https://files.pythonhosted.org/packages/a7/a6/c9b93519ac4effa74408c01642d04c71636faaafdfa51c8c00f22845301f/mkdocs_shareable_admonition-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1e9a509986af271ddd4106aa81f057c824d6f34530ed294b3c0a72ece2d4ca5d",
"md5": "237961a39a9aa036a4d1e5b282b615cc",
"sha256": "31a1c7d754503c47b0cd6e3629ac8d9ea6d8ca6109f9176f1a898213a5b407a0"
},
"downloads": -1,
"filename": "mkdocs_shareable_admonition-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "237961a39a9aa036a4d1e5b282b615cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 5452,
"upload_time": "2024-07-21T22:25:02",
"upload_time_iso_8601": "2024-07-21T22:25:02.884041Z",
"url": "https://files.pythonhosted.org/packages/1e/9a/509986af271ddd4106aa81f057c824d6f34530ed294b3c0a72ece2d4ca5d/mkdocs_shareable_admonition-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-21 22:25:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ianderrington",
"github_project": "mkdocs-shareable-admonition",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-shareable-admonition"
}
JSON
