{"id":15663993,"url":"https://github.com/facelessuser/mkdocs-material-extensions","last_synced_at":"2025-05-05T03:42:05.933Z","repository":{"id":47308011,"uuid":"255083905","full_name":"facelessuser/mkdocs-material-extensions","owner":"facelessuser","description":"Markdown extension resources for MkDocs Material","archived":false,"fork":false,"pushed_at":"2023-11-22T19:09:00.000Z","size":57,"stargazers_count":37,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-05T03:41:50.569Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facelessuser.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-12T13:04:22.000Z","updated_at":"2025-04-03T01:38:49.000Z","dependencies_parsed_at":"2023-10-16T09:12:35.988Z","dependency_job_id":"929afdd9-94f2-42e5-a42d-576888a8a6aa","html_url":"https://github.com/facelessuser/mkdocs-material-extensions","commit_stats":{"total_commits":32,"total_committers":2,"mean_commits":16.0,"dds":0.03125,"last_synced_commit":"80b1b252e4f1173359dbf38abf45adab2a11030b"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facelessuser%2Fmkdocs-material-extensions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facelessuser%2Fmkdocs-material-extensions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facelessuser%2Fmkdocs-material-extensions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facelessuser%2Fmkdocs-material-extensions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facelessuser","download_url":"https://codeload.github.com/facelessuser/mkdocs-material-extensions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252436240,"owners_count":21747467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T13:40:44.888Z","updated_at":"2025-05-05T03:42:05.916Z","avatar_url":"https://github.com/facelessuser.png","language":"Python","funding_links":["https://www.paypal.me/facelessuser"],"categories":[],"sub_categories":[],"readme":"[![Donate via PayPal][donate-image]][donate-link]\n[![Build][github-ci-image]][github-ci-link]\n[![Coverage Status][codecov-image]][codecov-link]\n[![PyPI Version][pypi-image]][pypi-link]\n[![PyPI - Python Version][python-image]][pypi-link]\n![License][license-image-mit]\n# MkDocs Material Extensions\n\n\u003e NOTE: This project is now deprecated as MkDocs for Material now implements this logic directly.\n\u003e Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and \n\u003e `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`\n\u003e functions provided by this library.\n\nMarkdown extension resources for [MkDocs for Material][mkdocs-material]\n\n## Install\n\nGenerally, just installing MkDocs Material will automatically install `mkdocs-material-extensions`. But if you had a\nneed to manually install it, you can use pip.\n\n```\npip install mkdocs-material-extensions\n```\n\nBut make sure you've also installed MkDocs Material as well as this won't work without it. \n\n```\npip install mkdocs-material\n```\n\n## Inline SVG Icons\n\nMkDocs Material provides numerous icons from Material, FontAwesome, and Octicons, but it does so by inlining the SVG\nicons into the source. Currently there is no easy way access these icons and arbitrarily insert them into Markdown\ncontent. Users must include the icon fonts themselves and do it with HTML.\n\nThis module allows you to use PyMdown Extensions' [Emoji][emoji] extension to enable easy insertion of MkDocs Material's\nSVG assets using simple `:emoji-syntax:`.  This is done by creating our own [emoji index][emoji-index] and\n[emoji generator][emoji-generator]. The custom index provides a modified version of the Emoji extensions Twemoji\nindex.\n\nIn addition to the custom index, you must also specify the associated custom generator. This will will find the\nappropriate icon and insert it into your Markdown content as an inlined SVG.\n\nExample:\n\n```yaml\nmarkdown_extensions:\n  - pymdownx.emoji:\n      emoji_index: !!python/name:materialx.emoji.twemoji\n      emoji_generator: !!python/name:materialx.emoji.to_svg\n```\n\nThen, using the folder structure of Material's `.icons` folder, you can specify icons:\n\n```\nWe can use Material Icons :material-airplane:.\n\nWe can also use Fontawesome Icons :fontawesome-solid-ambulance:.\n\nThat's not all, we can also use Octicons :octicons-octoface:.\n```\n\n## Using Local Custom Icons\n\nIn MkDocs, you can override theme assets locally, and even add assets to the theme. Unfortunately, the Markdown parsing\nprocess isn't aware of the MkDocs environment. Luckily, if you are using PyMdown Extensions 7.1, you can pass in custom\nicon paths that will be used when constructing the emoji index and include your custom SVG assets. If a folder path of\n`theme/my_icons` was given to the index builder, all icons under `my_project/my_icons`, even in sub-folders, would\nbecome part of the index.\n\n```yaml\nmarkdown_extensions:\n  - pymdownx.emoji:\n      emoji_index: !!python/name:materialx.emoji.twemoji\n      emoji_generator: !!python/name:materialx.emoji.to_svg\n      options:\n        custom_icons:\n          - theme/my_icons\n```\n\nIf given an icon at `my_project/my_icons/animals/bird.svg`, the icon would be available using the emoji syntax as\n`:animals-bird:`. Notice that the base folder that is provided doesn't contribute to the icon's name. Also, folders\nare separated with `-`. Folder names and icon names should be compatible with the emoji syntax, so special characters\nshould be avoided -- `-` and `_` are okay.\n\nYou can provide as many paths as you would like, and they will be evaluated in the order that they are specified. The\nMaterial theme's own icons will be evaluated after all custom paths. This allows a user to override Material's icons if\ndesired.\n\nIf an icon name is already in the index, the icon will not be added. It is recommended to always have your icons in\nsub-folders to help namespace them to avoid name collisions. In the example above, `bird` was under `animals` which\ncreated the name `:animals-bird:` and helped create a more unique name with less of a chance of creating a duplicate\nname with existing emoji and Material icons.\n\n[emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/\n[emoji-index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#custom-emoji-indexes\n[emoji-generator]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#custom-emoji-generators\n[mkdocs-material]: https://github.com/squidfunk/mkdocs-material\n\n[donate-image]: https://img.shields.io/badge/Donate-PayPal-3fabd1?logo=paypal\n[donate-link]: https://www.paypal.me/facelessuser\n[github-ci-image]: https://github.com/facelessuser/mkdocs-material-extensions/workflows/build/badge.svg?branch=master\u0026event=push\n[github-ci-link]: https://github.com/facelessuser/mkdocs-material-extensions/actions?query=workflow%3Abuild+branch%3Amaster\n[discord-image]: https://img.shields.io/discord/678289859768745989?logo=discord\u0026logoColor=aaaaaa\u0026color=mediumpurple\u0026labelColor=333333\n[discord-link]: https://discord.gg/TWs8Tgr\n[codecov-image]: https://img.shields.io/codecov/c/github/facelessuser/mkdocs-material-extensions/master.svg?logo=codecov\u0026logoColor=aaaaaa\u0026labelColor=333333\n[codecov-link]: https://codecov.io/github/facelessuser/mkdocs-material-extensions\n[pypi-image]: https://img.shields.io/pypi/v/mkdocs-material-extensions.svg?logo=pypi\u0026logoColor=aaaaaa\u0026labelColor=333333\n[pypi-link]: https://pypi.python.org/pypi/mkdocs-material-extensions\n[python-image]: https://img.shields.io/pypi/pyversions/mkdocs-material-extensions?logo=python\u0026logoColor=aaaaaa\u0026labelColor=333333\n[license-image-mit]: https://img.shields.io/badge/license-MIT-blue.svg?labelColor=333333\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacelessuser%2Fmkdocs-material-extensions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacelessuser%2Fmkdocs-material-extensions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacelessuser%2Fmkdocs-material-extensions/lists"}