Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oprypin/markdown-callouts
Markdown extension: a classier syntax for admonitions
https://github.com/oprypin/markdown-callouts
admonition markdown markdown-extension mkdocs python-markdown
Last synced: 2 days ago
JSON representation
Markdown extension: a classier syntax for admonitions
- Host: GitHub
- URL: https://github.com/oprypin/markdown-callouts
- Owner: oprypin
- License: mit
- Created: 2021-05-03T01:07:19.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-02-11T18:55:19.000Z (8 months ago)
- Last Synced: 2024-05-02T02:01:42.774Z (5 months ago)
- Topics: admonition, markdown, markdown-extension, mkdocs, python-markdown
- Language: Python
- Homepage: https://oprypin.github.io/markdown-callouts
- Size: 89.8 KB
- Stars: 23
- Watchers: 4
- Forks: 12
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# markdown-callouts
**Extension for [Python-Markdown][]: a classier syntax for [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)**
[](https://pypi.org/project/markdown-callouts/)
[](https://github.com/oprypin/markdown-callouts/blob/master/LICENSE.md)
[](https://github.com/oprypin/markdown-callouts/actions?query=event%3Apush+branch%3Amaster)
[python-markdown]: https://python-markdown.github.io/
[admonition]: https://python-markdown.github.io/extensions/admonition/
[mkdocs]: https://www.mkdocs.org/
[documentation site]: https://oprypin.github.io/markdown-callouts/
## Installation
```shell
pip install markdown-callouts
```
If using MkDocs, [enable the extension in **mkdocs.yml**](https://www.mkdocs.org/user-guide/configuration/#markdown_extensions):
```yaml
markdown_extensions:
- callouts
```
**Continue to the [documentation site][].**
## Usage
This adds a new block-level syntax to Markdown, to put a paragraph of text into a block that's specially highlighted and set apart from the rest of the text.
**Example:**
```markdown
NOTE: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
**Result**, [using *mkdocs-material*](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage):
Collapsible blocks also have a syntax for them:
```markdown
>? NOTE: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
> nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
> massa, nec semper lorem quam in massa.
```
This instead shows up as an initially-closed `` block.
### Graceful degradation
This extension produces the same results as the *[admonition][]* extension, but with a syntax that is much less intrusive and has a very reasonable fallback look for "vanilla" renderers.
E.g. compare what you would've seen above if we actually wrote that Markdown and fed it to GitHub's Markdown parser:
"Callouts" syntax
NOTE: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
"Admonition" syntax
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
---
**Continue to the [documentation site][].**