Git Product home page Git Product logo

markdown-callouts's Introduction

markdown-callouts

Extension for Python-Markdown: a classier syntax for admonitions

PyPI License GitHub Workflow Status

Installation

pip install markdown-callouts

If using MkDocs, enable the extension in mkdocs.yml:

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:

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:

Screenshot

Collapsible blocks also have a syntax for them:

>? 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 <details> 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.

markdown-callouts's People

Contributors

oprypin avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

markdown-callouts's Issues

Allow adding custom classes to the admonition

For example, to support this feature: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks

I currently don't have any ideas regarding how it would still make sense with "graceful degradation", there's just no way...

This (made up) syntax makes little sense to me, and anything similar would probably be just as noisy:

NOTE {.inline .end}: Hello, world!

So perhaps this would be the syntax, relying on attr_list:

NOTE: Hello, world!
{.inline .end}

> NOTE: Hello, world!
>
> Foo bar
{: #someid .someclass somekey='some value' }

Currently the latter produces this HTML, which is no good:

<div class="admonition note">
  <p class="admonition-title">
    Note
  </p>
  <p>
    Hello, world!
  </p>
  <p class="someclass" id="someid" somekey="some value">
    Foo bar
  </p>
</div>

But in fact, the current state is consistent with how blockquotes behave! -- regardless of the callout part, the classes get attached to the last paragraph of the blockquote. So I have some doubts on trying to do it in this exact way.

But in any case, we would need to be able to produce this HTML:

<div class="admonition note someclass" id="someid" somekey="some value">
  <p class="admonition-title">
    Note
  </p>
  <p>
    Hello, world!
  </p>
  <p>
    Foo bar
  </p>
</div>

Allow more than one word for the title

Current behaviour

At the moment the syntax is limited to one word for the title:

The syntax is: as the start of a paragraph, write a word in all capital letters, followed by a colon and a space

https://oprypin.github.io/markdown-callouts/#usage

REGEX = re.compile(r"(^ {0,3}> ?|\A)([A-Z]{2,}): (.*)", flags=re.M)

Feature request

It would be great if two or more words were allowed, e.g.

INSTALLATION REQUIREMENTS: 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.

Use case

Our use case: https://docs.laminas.dev/laminas-i18n/translation/#translation

> INSTALLATION REQUIREMENTS: The translation support of laminas-i18n depends on the
> [laminas-servicemanager](https://docs.laminas.dev/laminas-servicemanager/) component,
> so be sure to have it installed before getting started:
>
> ```bash
> $ composer require laminas/laminas-servicemanager
> ```

Allow custom admonition styling for Caution GitHub Alerts

It looks like there is special handling for Caution GitHub Alerts that styles them as Danger and prevents styling them with custom CSS.

For example, I tried adding the following CSS to style Caution and Important GitHub Alerts:

:root {
  --md-admonition-icon--important: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M 1.75,1.5 A 0.25,0.25 0 0 0 1.5,1.75 v 9.5 c 0,0.138 0.1120001,0.25 0.25,0.25 h 2 a 0.75,0.75 0 0 1 0.75,0.75 v 2.189453 l 2.7207031,-2.71875 A 0.749,0.749 0 0 1 7.75,11.5 h 6.5 A 0.25,0.25 0 0 0 14.5,11.25 V 1.75 A 0.25,0.25 0 0 0 14.25,1.5 Z M 7.8339844,3.0195313 A 0.75,0.75 0 0 1 8.75,3.75 v 2.5 a 0.75,0.75 0 0 1 -1.5,0 V 3.75 A 0.75,0.75 0 0 1 7.8339844,3.0195313 Z M 8,8 A 1,1 0 0 1 9,9 1,1 0 0 1 7,9 1,1 0 0 1 8,8 Z"/></svg>');
  --md-admonition-icon--caution: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="M 5.3105469,1.5 1.5,5.3105469 V 10.689453 L 5.3105469,14.5 H 10.689453 L 14.5,10.689453 V 5.3105469 L 10.689453,1.5 Z M 8,4 a 0.75,0.75 0 0 1 0.75,0.75 v 3.5 a 0.75,0.75 0 0 1 -1.5,0 V 4.75 A 0.75,0.75 0 0 1 8,4 Z m 0,6 a 1,1 0 0 1 0,2 1,1 0 0 1 0,-2 z"/></svg>');

}

.md-typeset .admonition.important,
.md-typeset details.important {
  border-color: #7c4dff;
}

.md-typeset .important>.admonition-title,
.md-typeset .important>summary {
  background-color: #7c4dff1a;
}

.md-typeset .important>.admonition-title::before,
.md-typeset .important>summary::before {
  background-color: #7c4dff;
  -webkit-mask-image: var(--md-admonition-icon--important);
  mask-image: var(--md-admonition-icon--important);
}

.md-typeset .admonition.caution,
.md-typeset details.caution {
  border-color: #ff1744;
}

.md-typeset .caution>.admonition-title,
.md-typeset .caution>summary {
  background-color: #ff17441a;
}

.md-typeset .caution>.admonition-title::before,
.md-typeset .caution>summary::before {
  background-color: #ff1744;
  -webkit-mask-image: var(--md-admonition-icon--caution);
  mask-image: var(--md-admonition-icon--caution);
}

Here is the result when - github-callouts is enabled (Important is styled with custom CSS, but Caution is not using custom CSS):

image

However, if I remove - github-callouts and use - markdown_gfm_admonition (from markdown-gfm-admonition extension) instead, both Important and Caution are styled using the custom CSS:

image

Would it be possible to have an option to disable the special handling of the Caution Alert so that it can be styled via custom CSS?

No way to disable on a list item

It seems I cannot disable the extension in lists items:

Supported formats:

- JSON: see this and that.

It will render as a note admonition with Json as title.
If I add a space before the dash or after it, nothing changes ๐Ÿ˜•

Allow arbitrary titles independent of the admonition class

Presently, we have just this:

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.

image

We need to come up with a syntax to be able to set a fully custom title, like this:

image

Some ideas:

  1. NOTE: **This is used as the title.** 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.

    (thanks @pawamoy)

  2. NOTE "This is used as the title": 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.
  3. NOTE (This is used as the title): 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.

For reference/inspiration: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types

Allow collapsible admonition blocks - <details>

Need to come up with some syntax to implement the equivalent of https://facelessuser.github.io/pymdown-extensions/extensions/details/#syntax

If the base syntax for callouts is this:

> NOTE: **This is used as the title.** 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.

How can we expand it to instead denote an initially closed <details> block and an initially open one?

image

Maybe this? I... really don't know.

>? NOTE: **Closed details.** Lorem ipsum dolor sit amet, consectetur

>! NOTE: **Open details.** Lorem ipsum dolor sit amet, consectetur

Fallback look:

? NOTE: Closed details. Lorem ipsum dolor sit amet, consectetur

! NOTE: Open details. Lorem ipsum dolor sit amet, consectetur

Custom callouts

Currently, only 4 callouts are supported. IMPORTANT: TIP: INFO: NOTE:

I propose the callout syntax to be changed to

> **Tip** This is a tip

Tip This is a tip

Any name should be allowed in callouts. Also, a custom logo will be great.

Like

๐Ÿ“ข Announcement This is an announcement.

The emoji needs to be translated to the nearest possible logo in mkdocs, if not available, use the emoji directly.


I am interested in implementing this. But don't know where to start. Any link would be really helpful. In the meantime, I am searching.

Support Note and Warning blockquote as hint container

Would you like to support following github markdown style for mkdocs, and it'll be perfect.

Note
Some text here

Note: Some text here

Note: Some text here
Addtional Content

Warning
Some text here

Warning: Some text here

Warning: Some text here
Addtional Content

> **Note**
> Some text here

> **Note**: Some text here

> **Note**: Some text here
> Addtional Content

> **Warning**
> Some text here

> **Warning**: Some text here

> **Warning**: Some text here
> Addtional Content

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.