Inline blocks extension syntax

[joapuiib]

I've been using a lot the new block caption extensions and I love it. However, I think the block syntax could be simplified by having an "inline" syntax.

From squidfunk/mkdocs-material#7654:

I'm still not the biggest fan of the blocks syntax for the noise it adds, so please add this as an additional way of using figures.

Right now, captions are written with the following syntax:

- pymdownx.blocks.caption:
    auto: true
    types:
      - caption
      - name: attribution
        classes: attribution
      - name: figure-caption
        prefix: 'Figura {}.'

![img](placeholder.png)
/// attribution
Unknown author
///
/// figure-caption | < ^1
Caption
///

With inline syntax, could become:

![img](placeholder.png)
/// attribution: Unknown author
/// figure-caption | < ^1 : Caption

This is just a consideration about the block syntax and an idea of how it could be improved. I know "inline" syntax would increase complexity a lot.

[facelessuser]

I'm still not the biggest fan of the blocks syntax for the noise it adds, so please add this as an additional way of using figures.

1. While I am aware that he, and others on occasion, have had subjective opinions about the syntax, there are very real reasons the syntax is as it is. This is a subjective opinion, and while valid, is no less valid than others. Some have complained that they hate having to indent blocks like they do with the currently preferred Admonition extension. If trying to resolve which is more important "too much noise" or "indents are cumbersome" who wins? The argument is subjective. I cannot please everyone. With that said, there are also other considerations that were not as subjective when coming up with the current syntax.

2. I should also note that I did not develop this in a black box and gave ample opportunity to him, and others, to participate in the conversation if they so chose. I also invited them to do so. A handful of people did, many did not. I would have loved to hear alternatives from him if he had opinions to the contrary, but I never received any. I also realize that he was very much heavily involved in Material work as well, so his involvement level is completely understandable, so I'm not complaining that he was not involved, only that it is too late to complain now. Additionally, had he been more involved in the process, he may have found the syntax to be more understandable due to other constraints I was operating in.

3. The implementation had to be generic. I was growing tired of every time I had a new plugin idea, I had to invent a new syntax that seemed intuitive and did not conflict with some other custom syntax out in the wild. After some time, you quickly run out of intuitive syntax, and the syntax becomes more convoluted as you implement more and more plugins. At this point, I needed a single syntax that I could reuse for any new functionality, but it had to be generic, and it had to apply to all blocks.

4. Also note this syntax is designed for block content, not inline content. Block content was going to give me the greatest payoff for the kinds of plugin ideas I had for the future.

5. Blocks are meant to handle block content of any complexity. To do this, you need a real way to identify the start and end of content. If you were dealing with single blocks with no empty new lines, you could declare a header and no footer to the content, but content can be much more complex, there must be a way to signify a start and an end. For maintainability, I need the syntax to be generic. It needs to apply to all cases, so it handles blocks of any complexity.

6. The section of the header after | is meant to handle any content. It is used to define titles in admonitions and other Block extensions that can contain any characters. We cannot add a new restriction to allow structural syntax on that line.

7. There are also other reasons I chose a "fenced" approach instead of "indented" approach, or other approaches. The indented admonition approach is currently flawed within the Python Markdown infrastructure. Its forced indentation can lead to confusion when using some other features: Indented <script> tags are parsed as Markdown instead of being skipped. Python-Markdown/markdown#1471 (comment). It is also more difficult to implement such things as hooks for on_end parsing of the blocks for generic block plugins as the end is never known when Blocks has control. We need an explicit end to easily identify when parsing is done and to give the necessary control to those implementing block plugins.

The closest thing I have to custom inline handling is this: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#custom-inline-blocks. I don't think this would apply well to image captions though.

[facelessuser]

Thanks for taking the time and sorry if I'm a little annoying 😅

You're not annoying, just asking questions. I appreciate the engagement. There's nothing wrong with seeking to improve things.

[joapuiib]

Hmm, I see.

Possible alternatives:

• Use another "rare" marker or a string as a separator.
• Just allow inline syntax for a specific subset of block extensions.
  • Maybe it doesn't make sense to allow inline HTML or admonition block, but it could make sense in captions. In this kind of blocks, no arbitrary text is allowed in the block header and could be used as the caption content.

[facelessuser]

Captions can have complex content. Captions are not inherently single lines. Yes they can be single lines, but they are not guaranteed to be such. I don't feel like captions lend well to the header field. Some cases do, but there are plenty that don't. Across the internet, you can find plenty of examples of figures with rich captions that equate to a paragraph of description, or more.

I don't think I'm interested in adding complexity to treat blocks as single lines in some cases (using the header field) and then other times allowing them to use the body. I think this convolutes the extension in a way I don't really like.

There were talks early on about maybe allowing things like /// note | title /// as some wanted to specify admonitions without content. I cannot predict all the ways in which people may wish to use the header field in the future, so I wasn't keen on limiting it as I wanted to allow those who developed their own Block extensions to be able to express whatever they needed in that field. If there was a way I would limit things to a single line, it would probably be by ending the line with normal closing, but this is something I passed on in the past.

I've stated before that I have accepted that I will not be able to please everyone. And yes, that does mean that my own opinions will paint (taint 🙃) the final implementation of the extension. Trying to add options, exceptions, and the like to make everyone happy adds complexity to the extensions and does affect maintainability.

[joapuiib]

I understand 👍🏼

I'll try to extend Caption extension to allow inline syntax in a separate package, since I'll be writing a lot of single line captions.

/// figure-caption | < ^1 : Caption

Thanks!

[facelessuser]

Sounds good

[joapuiib]

A brief update on this topic in case it is useful to someone.

I've created pymdownx-inline-blocks, a Markdown extension which provides an inline block syntax and converts it to the regular block syntax.

![alt](url)
/// caption | .shadow : This is a caption

Will be transformed to

![alt](url)
/// caption | .shadow
This is a caption
///

---

To overcome the limitation where the default delimiter (:) is used as part of the block definition, I've designed a syntax where the delimiter can be set for each block.

///<delimiter?> block | modifiers <delimiter> content

Example:

///~ html | div[style='border: 1px solid red;'] ~ some *markdown* content

Becomes

/// html | div[style='border: 1px solid red;']
some *markdown* content
///

---

Any feedback is welcome!