This commit is contained in:
CreaRobotics committed 2026-03-02 11:34:40 +01:00
1 parent 6ccab0347b
commit 954a2fd6d6
18684 files changed
+601012 -190

No files matched your search

@@ -0,0 +1,139 @@
Metadata-Version: 2.1
Name: mkdocs-material-extensions
Version: 1.3.1
Summary: Extension pack for Python Markdown and MkDocs Material.
Project-URL: Homepage, https://github.com/facelessuser/mkdocs-material-extensions
Author-email: Isaac Muse <Isaac.Muse@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Keywords: extensions,markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Filters
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.8
Description-Content-Type: text/markdown
[![Donate via PayPal][donate-image]][donate-link]
[![Build][github-ci-image]][github-ci-link]
[![Coverage Status][codecov-image]][codecov-link]
[![PyPI Version][pypi-image]][pypi-link]
[![PyPI - Python Version][python-image]][pypi-link]
![License][license-image-mit]
# MkDocs Material Extensions
> NOTE: This project is now deprecated as MkDocs for Material now implements this logic directly.
> Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and
> `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`
> functions provided by this library.
Markdown extension resources for [MkDocs for Material][mkdocs-material]
## Install
Generally, just installing MkDocs Material will automatically install `mkdocs-material-extensions`. But if you had a
need to manually install it, you can use pip.
```
pip install mkdocs-material-extensions
```
But make sure you've also installed MkDocs Material as well as this won't work without it.
```
pip install mkdocs-material
```
## Inline SVG Icons
MkDocs Material provides numerous icons from Material, FontAwesome, and Octicons, but it does so by inlining the SVG
icons into the source. Currently there is no easy way access these icons and arbitrarily insert them into Markdown
content. Users must include the icon fonts themselves and do it with HTML.
This module allows you to use PyMdown Extensions' [Emoji][emoji] extension to enable easy insertion of MkDocs Material's
SVG assets using simple `:emoji-syntax:`. This is done by creating our own [emoji index][emoji-index] and
[emoji generator][emoji-generator]. The custom index provides a modified version of the Emoji extensions Twemoji
index.
In addition to the custom index, you must also specify the associated custom generator. This will will find the
appropriate icon and insert it into your Markdown content as an inlined SVG.
Example:
```yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
```
Then, using the folder structure of Material's `.icons` folder, you can specify icons:
```
We can use Material Icons :material-airplane:.
We can also use Fontawesome Icons :fontawesome-solid-ambulance:.
That's not all, we can also use Octicons :octicons-octoface:.
```
## Using Local Custom Icons
In MkDocs, you can override theme assets locally, and even add assets to the theme. Unfortunately, the Markdown parsing
process isn't aware of the MkDocs environment. Luckily, if you are using PyMdown Extensions 7.1, you can pass in custom
icon paths that will be used when constructing the emoji index and include your custom SVG assets. If a folder path of
`theme/my_icons` was given to the index builder, all icons under `my_project/my_icons`, even in sub-folders, would
become part of the index.
```yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
options:
custom_icons:
- theme/my_icons
```
If given an icon at `my_project/my_icons/animals/bird.svg`, the icon would be available using the emoji syntax as
`:animals-bird:`. Notice that the base folder that is provided doesn't contribute to the icon's name. Also, folders
are separated with `-`. Folder names and icon names should be compatible with the emoji syntax, so special characters
should be avoided -- `-` and `_` are okay.
You can provide as many paths as you would like, and they will be evaluated in the order that they are specified. The
Material theme's own icons will be evaluated after all custom paths. This allows a user to override Material's icons if
desired.
If an icon name is already in the index, the icon will not be added. It is recommended to always have your icons in
sub-folders to help namespace them to avoid name collisions. In the example above, `bird` was under `animals` which
created the name `:animals-bird:` and helped create a more unique name with less of a chance of creating a duplicate
name with existing emoji and Material icons.
[emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[emoji-index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#custom-emoji-indexes
[emoji-generator]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#custom-emoji-generators
[mkdocs-material]: https://github.com/squidfunk/mkdocs-material
[donate-image]: https://img.shields.io/badge/Donate-PayPal-3fabd1?logo=paypal
[donate-link]: https://www.paypal.me/facelessuser
[github-ci-image]: https://github.com/facelessuser/mkdocs-material-extensions/workflows/build/badge.svg?branch=master&event=push
[github-ci-link]: https://github.com/facelessuser/mkdocs-material-extensions/actions?query=workflow%3Abuild+branch%3Amaster
[discord-image]: https://img.shields.io/discord/678289859768745989?logo=discord&logoColor=aaaaaa&color=mediumpurple&labelColor=333333
[discord-link]: https://discord.gg/TWs8Tgr
[codecov-image]: https://img.shields.io/codecov/c/github/facelessuser/mkdocs-material-extensions/master.svg?logo=codecov&logoColor=aaaaaa&labelColor=333333
[codecov-link]: https://codecov.io/github/facelessuser/mkdocs-material-extensions
[pypi-image]: https://img.shields.io/pypi/v/mkdocs-material-extensions.svg?logo=pypi&logoColor=aaaaaa&labelColor=333333
[pypi-link]: https://pypi.python.org/pypi/mkdocs-material-extensions
[python-image]: https://img.shields.io/pypi/pyversions/mkdocs-material-extensions?logo=python&logoColor=aaaaaa&labelColor=333333
[license-image-mit]: https://img.shields.io/badge/license-MIT-blue.svg?labelColor=333333
@@ -0,0 +1,11 @@
materialx/__init__.py,sha256=Izvt8OToVN0IS8Dss30k_OF8hSsi05kbja7xcYRYkIY,34
materialx/__meta__.py,sha256=b2fknCkoYcZSgyTuya0IldYu_mt1ohZsQQqcWQo5s38,6677
materialx/__pycache__/__init__.cpython-312.pyc,,
materialx/__pycache__/__meta__.cpython-312.pyc,,
materialx/__pycache__/emoji.cpython-312.pyc,,
materialx/emoji.py,sha256=ih3Y8lFxutxB5pfYq4s3Gtny27xmawc8I8Y8DNe9rhI,4928
mkdocs_material_extensions-1.3.1.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
mkdocs_material_extensions-1.3.1.dist-info/METADATA,sha256=CmvA6Xy_MFV5iCmCyd-nFihCdwegzy1XdCErBvQS5yA,6934
mkdocs_material_extensions-1.3.1.dist-info/RECORD,,
mkdocs_material_extensions-1.3.1.dist-info/WHEEL,sha256=9QBuHhg6FNW7lppboF2vKVbCGTVzsFykgRQjjlajrhA,87
mkdocs_material_extensions-1.3.1.dist-info/licenses/LICENSE.md,sha256=s8wUkDHYPsJyrOSZ5iIXxQZuAgClVg2BjZDNx7wFQDw,1067
@@ -0,0 +1,4 @@
Wheel-Version: 1.0
Generator: hatchling 1.18.0
Root-Is-Purelib: true
Tag: py3-none-any
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2021 Isaac Muse
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.