# GitHub Admonitions for MkDocs
Convert [GitHub admonitions](https://github.com/orgs/community/discussions/16925)
to [`mkdocs` admonitions](https://python-markdown.github.io/extensions/admonition/)
when building docs, so that you can have admonitions on GitHub _and_ in the
documentation from the same file.
> [!TIP]
> This is an admonition. They are a useful tool to attract attention to information.
## Usage
To install the plugin:
```bash
python -m pip install mkdocs-github-admonitions-plugin
```
Then in your `mkdocs.yml` file, add the plugin:
```yaml
plugins:
- gh-admonitions
```
Now you can write Github-compatible admonitions, and they will be
automatically converted when used in [`mkdocs`][mm] pages.
## Why is this needed?
Both Github and [`mkdocs`][mm] support admonitions from their markdown flavors.
Unfortunately, their flavors are different.
A Github admonition is written like this:
```
> [!TIP]
> This is the Github admonition syntax.
```
And [`mkdocs`][mm] admonitions are written like this:
```
!!! tip
This is the mkdocs-materials admonition syntax.
```
So an admonition in your documentation will render correctly on either Github
or in your [`mkdocs`][mm] pages, but not both. With this plugin, you write
the admonition once in Github syntax, and it will still show correctly in the
built [`mkdocs`][mm] pages!
## Limitations
The [`mkdocs`][mm] admonitions are much more powerful. They can feature
titles. They have more types, and you can add custom ones. You can render inline
admonitions. They can be collapsable, and be collapsed by default.
And much more.
But since the GitHub syntax has none of that, this tool can not offer such
[`mkdocs`][mm] admonitions to be generated. All admonitions will be
converted to non-collapsed title-less admonitions.
GitHub admonitions feature two types which are not supported by [`mkdocs`][mm]:
`caution` and `important`. In converting these admonitions, we will preserve their title,
but use the `danger` and `warning` symbol and color, respectively.
## Examples
Here is a gallery with various admonitions.
They should show up correctly on the built documentation too!
> [!tip]
> This is normally formatted. Type in lower case. No extra spaces.
> It contains two lines in markdown, but only a soft linebreak.
> [!CAUTION]
> This admonition has:
>
> - ALL CAPS in the type
> - a list
>
> Note that this admonition uses the "danger" symbol with "Caution" title.
> [!Important]
> This contains `inline` and
> ```python
> import this # python code in ticks
> ```
>
> and code block with spaces
>
> Note that this admonition uses the "warning" symbol with "Important" title.
> [!note]
> And this admonition contains an empty line
>
> That only has a `>` character in markdown.
> [!warning]
> Admonitions may contains quotes
> > Quotes always contain great wisdom.
But pay attention! There may be admonitions which are really just code:
```text
> [!note]
> This is not an admonition.
```
## Disclaimer
This is an independent project and not affiliated with GitHub in any way.
[mm]: https://www.mkdocs.org
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-github-admonitions-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "admonition, github, material, mkdocs",
"author": "Pieter Gijsbers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/65/13/a2b2b81604481569982fdaf51f0746f320df303efbd13d7b74fbf7b2c3a4/mkdocs_github_admonitions_plugin-0.0.3.tar.gz",
"platform": null,
"description": "# 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\n> [!TIP]\n> 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> [!TIP]\n> 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> [!tip]\n> This is normally formatted. Type in lower case. No extra spaces.\n> It contains two lines in markdown, but only a soft linebreak.\n\n> [!CAUTION] \n> This admonition has: \n> \n> - ALL CAPS in the type\n> - a list\n> \n> Note that this admonition uses the \"danger\" symbol with \"Caution\" title.\n\n> [!Important]\n> This contains `inline` and\n> ```python\n> import this # python code in ticks\n> ```\n>\n> and code block with spaces\n>\n> Note that this admonition uses the \"warning\" symbol with \"Important\" title.\n\n> [!note]\n> And this admonition contains an empty line\n>\n> That only has a `>` character in markdown.\n\n> [!warning]\n> Admonitions may contains quotes\n> > Quotes always contain great wisdom. \n\nBut pay attention! There may be admonitions which are really just code:\n```text\n> [!note]\n> 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",
"bugtrack_url": null,
"license": null,
"summary": "Convert GitHub admonitions to mkdocs syntax when building docs.",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://pgijsbers.github.io/admonitions",
"Issues": "https://www.github.com/pgijsbers/admonitions/issues",
"Repository": "https://www.github.com/pgijsbers/admonitions.git"
},
"split_keywords": [
"admonition",
" github",
" material",
" mkdocs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d287650f2cbd07f142034d84357ac651586748032546287ba70e90244180b92c",
"md5": "958593d170344e3d760d10e344c6cddd",
"sha256": "cb06f56e5b51e5d7b22fcbb4ab632079e3082b7f37bdbeb20cc9fd8a7c5e1657"
},
"downloads": -1,
"filename": "mkdocs_github_admonitions_plugin-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "958593d170344e3d760d10e344c6cddd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5043,
"upload_time": "2024-10-23T19:30:38",
"upload_time_iso_8601": "2024-10-23T19:30:38.195415Z",
"url": "https://files.pythonhosted.org/packages/d2/87/650f2cbd07f142034d84357ac651586748032546287ba70e90244180b92c/mkdocs_github_admonitions_plugin-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6513a2b2b81604481569982fdaf51f0746f320df303efbd13d7b74fbf7b2c3a4",
"md5": "f1f5381876de67af58ad15362200ddc1",
"sha256": "4fd3ca88157c18c5f0cc4420c1a7f73ed1ed3f1886f41d6ce869932e90f38c48"
},
"downloads": -1,
"filename": "mkdocs_github_admonitions_plugin-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "f1f5381876de67af58ad15362200ddc1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3998,
"upload_time": "2024-10-23T19:30:39",
"upload_time_iso_8601": "2024-10-23T19:30:39.095549Z",
"url": "https://files.pythonhosted.org/packages/65/13/a2b2b81604481569982fdaf51f0746f320df303efbd13d7b74fbf7b2c3a4/mkdocs_github_admonitions_plugin-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 19:30:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pgijsbers",
"github_project": "admonitions",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-github-admonitions-plugin"
}
JSON
