{"id":15107080,"url":"https://github.com/pgijsbers/admonitions","last_synced_at":"2025-07-27T10:30:43.382Z","repository":{"id":239283079,"uuid":"798455933","full_name":"PGijsbers/admonitions","owner":"PGijsbers","description":"Plugin to convert GitHub-style admonitions to `mkdocs-material`-style admonitions when building docs.","archived":false,"fork":false,"pushed_at":"2024-10-22T21:18:19.000Z","size":590,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-01T02:50:53.854Z","etag":null,"topics":["admonition","documentation","mkdocs-material","plugin"],"latest_commit_sha":null,"homepage":"https://pgijsbers.github.io/admonitions","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/PGijsbers.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-05-09T20:15:11.000Z","updated_at":"2024-11-25T21:37:57.000Z","dependencies_parsed_at":"2024-09-16T08:54:08.908Z","dependency_job_id":null,"html_url":"https://github.com/PGijsbers/admonitions","commit_stats":null,"previous_names":["pgijsbers/admonitions"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PGijsbers%2Fadmonitions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PGijsbers%2Fadmonitions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PGijsbers%2Fadmonitions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PGijsbers%2Fadmonitions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PGijsbers","download_url":"https://codeload.github.com/PGijsbers/admonitions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227475929,"owners_count":17779415,"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":["admonition","documentation","mkdocs-material","plugin"],"created_at":"2024-09-25T21:04:16.345Z","updated_at":"2025-07-27T10:30:43.376Z","avatar_url":"https://github.com/PGijsbers.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Admonitions for MkDocs\n\nConvert [GitHub admonitions](https://github.com/orgs/community/discussions/16925)\nto [`mkdocs` admonitions](https://python-markdown.github.io/extensions/admonition/) \nwhen building docs, so that you can have admonitions on GitHub _and_ in the \ndocumentation from the same file.\n\nNow also supporting GitLab admonitions ([alerts](https://docs.gitlab.com/user/markdown/#alerts), thanks @pismy!).\n\n\u003e [!TIP]\n\u003e This is an admonition. They are a useful tool to attract attention to information.\n\n## Usage\n\nTo install the plugin:\n\n```bash\npython -m pip install mkdocs-github-admonitions-plugin\n```\n\nThen in your `mkdocs.yml` file, add the plugin:\n\n```yaml\nplugins:\n  - gh-admonitions\n```\n\nNow you can write GitHub-compatible admonitions, and they will be \nautomatically converted when used in [`mkdocs`][mm] pages.\n\n## Why is this needed?\n\nBoth GitHub and [`mkdocs`][mm] support admonitions from their markdown flavors.\nUnfortunately, their flavors are different. \nA GitHub admonition is written like this:\n\n```\n\u003e [!TIP]\n\u003e This is the GitHub admonition syntax.\n```\n\nAnd [`mkdocs`][mm] admonitions are written like this:\n\n```\n!!! tip\n\n    This is the mkdocs-materials admonition syntax.\n```\n\nSo an admonition in your documentation will render correctly on either GitHub\nor in your [`mkdocs`][mm] pages, but not both. With this plugin, you write \nthe admonition once in GitHub syntax, and it will still show correctly in the\nbuilt [`mkdocs`][mm] pages!\n\n## Limitations\n\nThe [`mkdocs`][mm] admonitions are much more powerful. They can feature\ntitles. They have more types, and you can add custom ones. You can render inline\nadmonitions. They can be collapsable, and be collapsed by default.\nAnd much more. \n\nBut since the GitHub syntax has none of that, this tool can not offer such\n[`mkdocs`][mm] admonitions to be generated. All admonitions will be\nconverted to non-collapsed title-less admonitions.\n\nGitHub admonitions feature two types which are not supported by [`mkdocs`][mm]:\n`caution` and `important`. In converting these admonitions, we will preserve their title,\nbut use the `danger` and `warning` symbol and color, respectively.\n\n## Examples\n\nHere is a gallery with various admonitions.\nThey should show up correctly on the built documentation too!\n\n\u003e [!tip]\n\u003e This is normally formatted. Type in lower case. No extra spaces.\n\u003e It contains two lines in markdown, but only a soft linebreak.\n\n\u003e   [!CAUTION]    \n\u003e This admonition has:  \n\u003e \n\u003e   - ALL CAPS in the type\n\u003e   - a list\n\u003e \n\u003e Note that this admonition uses the \"danger\" symbol with \"Caution\" title.\n\n\u003e [!Important]\n\u003e This contains `inline` and\n\u003e ```python\n\u003e import this  # python code in ticks\n\u003e ```\n\u003e\n\u003e     and code block with spaces\n\u003e\n\u003e Note that this admonition uses the \"warning\" symbol with \"Important\" title.\n\n\u003e [!note]\n\u003e And this admonition contains an empty line\n\u003e\n\u003e That only has a `\u003e` character in markdown.\n\n\u003e [!warning]\n\u003e Admonitions may contains quotes\n\u003e \u003e Quotes always contain great wisdom. \n\nBut pay attention! There may be admonitions which are really just code:\n```text\n\u003e [!note]\n\u003e This is not an admonition.\n```\n\n## Disclaimer\n\nThis is an independent project and not affiliated with GitHub in any way.\n\n[mm]: https://www.mkdocs.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgijsbers%2Fadmonitions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgijsbers%2Fadmonitions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgijsbers%2Fadmonitions/lists"}