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: 3 months 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 (11 months ago)
• Last Synced: 2024-05-02T02:01:42.774Z (8 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)**

[![PyPI](https://img.shields.io/pypi/v/markdown-callouts)](https://pypi.org/project/markdown-callouts/)

[![License](https://img.shields.io/github/license/oprypin/markdown-callouts)](https://github.com/oprypin/markdown-callouts/blob/master/LICENSE.md)

[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/oprypin/markdown-callouts/ci.yml.svg)](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):

![Screenshot](https://user-images.githubusercontent.com/371383/119063216-dc001700-b9d8-11eb-8092-763e5d02d9f4.png)

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][].**