New Blocks Extensions in 9.10! #1973
Replies: 22 comments 73 replies
-
|
Release has been made. |
Beta Was this translation helpful? Give feedback.
-
|
Should I be able to use an Should I move this to an "Issue"? Given /// html | a[src="./basics/getting-started/"]
### Getting Started
More content that may use markdown.
///I receive an error: full errorThese elements (just for testing) do not give an error: Update (after the reply): I was using |
Beta Was this translation helpful? Give feedback.
-
|
I'm not sure exactly what you are doing as the content you are wrapping with an Anyways, let's look at the example. You are using an inline element to wrap what looks like block content, so I expect we will get an import markdown
MD = """
/// html | a[src="./basics/getting-started/"]
### Getting Started
More content that may use markdown.
///
"""
print(markdown.markdown(
MD,
extensions=['pymdownx.blocks.html']
))Output: <a src="./basics/getting-started/">### Getting Started
More content that may use markdown.</a>Now, I assume you want the content inside to be treated like a block, so let's try that: import markdown
MD = """
/// html | a[src="./basics/getting-started/"]
markdown: block
### Getting Started
More content that may use markdown.
///
"""
print(markdown.markdown(
MD,
extensions=['pymdownx.blocks.html']
))Output: <a src="./basics/getting-started/"><h3>Getting Started</h3><p>More content that may use markdown.</p></a>Now, everything seems to work exactly as expected. Your error seems to be complaining about a URL. Is it possible you did not specify your page reference properly and it can't be found? That is something you will have to look into though. From what I see, the HTML block extension is working as expected. |
Beta Was this translation helpful? Give feedback.
-
|
The extension is working as expected. I am unfamiliar with parsing markdown. Thank you for your patience and ability to [suffer] my ignorance. Using Using P.S. I believe the |
Beta Was this translation helpful? Give feedback.
-
|
HTML may allow you to wrap block elements with Anyways, I'm glad you figured it out. |
Beta Was this translation helpful? Give feedback.
-
|
I just released version 0.1 of bootstrap4markdown which uses Blocks to define some Bootstrap components. So far only alerts and carousels are supported. |
Beta Was this translation helpful? Give feedback.
-
|
Very cool, glad to see it being used! |
Beta Was this translation helpful? Give feedback.
-
|
On the initial documentation page when it lists the different extensions associated with blocks it reads:
when it really should be:
|
Beta Was this translation helpful? Give feedback.
-
|
Hmm, yeah, I guess we are specifying the module names, not the block names. |
Beta Was this translation helpful? Give feedback.
-
|
Could |
Beta Was this translation helpful? Give feedback.
-
|
We specify the same defaults that the original admonitions did for parity: https://github.com/facelessuser/pymdown-extensions/blob/main/pymdownx/blocks/admonition.py#L75. If you'd like a different set, simply specify them in your configuration: https://github.com/facelessuser/pymdown-extensions/blob/main/mkdocs.yml#L175 |
Beta Was this translation helpful? Give feedback.
-
|
alright, thanks |
Beta Was this translation helpful? Give feedback.
-
|
Making it flexible in this way makes it easy for anyone to use any convention they like. I should correct things slightly, the defaults come from the original reference that Python Markdown based admonitions off of: https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions. But yeah, defaults are kind of arbitrary, and even I override them. |
Beta Was this translation helpful? Give feedback.
-
|
As a historical note, when Python-Markdown's admonitions were first created, it was intended to be a clone of the docutils feature of the same name. The idea at the time was something like this: "Hey docutils user, we have that feature too." However, for someone who has never used docutils, that would be meaningless I suppose. However, the name has been in use in Python-Markdown for many years now so it doesn't make sense to change it IMO. |
Beta Was this translation helpful? Give feedback.
-
|
I have no intentions of changing the defaults. I think they are fine and the historical background is more than sufficient reason to keep them as they are. As long as it can be overridden, which it can, I have no issues. |
Beta Was this translation helpful? Give feedback.
-
|
Really like this syntax direction. I wonder if there's room to make the specifying of details more ergonomic. Class namesDoes present syntax presume blocks names to not contain spaces? If so: it'd be nice to take words preceding the block name and read them as classes. e.g Open/closedIt'd also be nice to shortcut the Combined with the above would make for some really satisfying fallbacks to plain text. |
Beta Was this translation helpful? Give feedback.
-
|
I can understand that people coming from the old legacy details format may want something similar to what they knew before, but that was a details-specific approach and this is a generic block syntax. We keep the name field simple so we can quickly parse, identify, and execute a block, I'm probably not interested in expanding this field and its functionality when we already have an easy way to set any and all attribute types via If you want things a bit more compact, you can even compress the options to one line if you choose: |
Beta Was this translation helpful? Give feedback.
-
|
Looks like |
Beta Was this translation helpful? Give feedback.
-
|
right. clear, glad I got an answer so quick. Thanks all, loving the unindented way to define tabs |
Beta Was this translation helpful? Give feedback.
-
|
Yep, I don't use the old indented format anymore. |
Beta Was this translation helpful? Give feedback.
-
|
I like it too, primarely because VS Code can now do proper highlighting... Tho, personally is that indendet options thing just frustrating for me... But that's just a personal thing and not too much of a bother. |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, we went round and round about how to expose the options. It's the least invasive approach, TBH. I had considered using |
Beta Was this translation helpful? Give feedback.
-
|
The only alternative I could think of is using a character to prefix the lines with to indicate options... Like as an example: Tho, I can see issues here, namely:
So I guess the space one is a somewhat good compromise for this situation. |
Beta Was this translation helpful? Give feedback.
-
|
Is there a way to not include the title? When I define this in the original admonition does it not display any title: However, since the way you define titles in blocks is different, I can't use the above. And using this here won't work either: It will use the admonition type as title then. And using a So, is there a way in blocks to have it not include the title? |
Beta Was this translation helpful? Give feedback.
-
|
If not, then maybe an option like |
Beta Was this translation helpful? Give feedback.
-
|
It may be that when using a special type that it uses the class name as a title. It's possible we did not special case |
Beta Was this translation helpful? Give feedback.
-
|
So, looking into this more. It works only for |
Beta Was this translation helpful? Give feedback.
-
|
PR with fix: #2235 |
Beta Was this translation helpful? Give feedback.
-
|
Would it be possible to have an option to override what title is being displayed by default for an admonition block if no title is defined? Like, f.e. markdown_extensions:
- pymdownx.blocks.admonition:
types:
- custom # custom admonition type
titles:
custom: Custom TitleThis would use while reducing the number of times to write the title... Would also help if you want to change the title, because then you only change it once instead of n times... |
Beta Was this translation helpful? Give feedback.
-
|
This probably isn't a bad idea and could be applied to details which are used in a similar fashion. Maybe we can simplify it and just allow type to accept a dictionary or a string. markdown_extensions:
- pymdownx.blocks.admonition:
types:
- note
- name: custom
title: Custom Title |
Beta Was this translation helpful? Give feedback.
-
|
Draft PR is up, still some work to do, but this will be customizable in the next release. #2241 |
Beta Was this translation helpful? Give feedback.
-
|
I wonder how you all match opening block sequence with the closing one when you have a big tab/admonition? Consider the following example: It is hard to match opening and ending blocks without ide to color tagging them. |
Beta Was this translation helpful? Give feedback.
-
|
Maybe someone could make an extension/plugin for VSCode to have this blog-syntax highlighted (Maybe using a system similar to rainbow brackets)... |
Beta Was this translation helpful? Give feedback.
-
|
No, it is currently just fences. You can use different numbers of |
Beta Was this translation helpful? Give feedback.
-
|
I don't use VSCode, so it won't be me 🙃. |
Beta Was this translation helpful? Give feedback.
-
|
I only use it because installing and updating Notepad++ became a huge pain (Constantly had an outdated, broken version installed for some reason) |
Beta Was this translation helpful? Give feedback.
-
|
I hated Notepad++. VSCode isn't bad, I have it installed and occasionally open it, but it is not my "go to" for anything. |
Beta Was this translation helpful? Give feedback.
-
|
I love this new syntax! 🚀 🎉 I wrote a script to automatize upgrading the syntax of my admonition blocks in my markdown files. I just used it for SQLModel, I'll use it later to also upgrade FastAPI, Typer, and Asyncer. import os
import re
import subprocess
from pathlib import Path
base_dir = Path(__file__).parent.parent
def update_admonition():
os.chdir(base_dir)
md_files = list(Path("docs").glob("**/*.md"))
# md_files = [Path("docs/db-to-code.md")]
re_str = r"!!! (?P<type>[^\n\"]*)\s?(\"(?P<title>[^\n\"]*)\")?\n(?P<content>(\n| .*)*)\n*"
# md_file = md_files[25]
for md_file in md_files:
content = md_file.read_text()
def replace(match: re.Match):
type_ = match.group("type")
title = match.group("title")
block = match.group("content")
deindented_block = block.replace(" ", "")
result = f"/// {type_}"
if title:
result += f" | {title}"
result += f"\n\n{deindented_block.strip()}\n\n"
result += "///\n\n"
return result
new_content = re.sub(re_str, replace, content)
md_file.write_text(new_content)
if __name__ == "__main__":
update_admonition() |
Beta Was this translation helpful? Give feedback.
-
|
Great to here! Thanks for sharing your script, I'm sure it'll help others migrate. |
Beta Was this translation helpful? Give feedback.
-
|
Another script to update HTML details, also used in SQLModel (fastapi/sqlmodel#713) 🚀 : import os
import re
from pathlib import Path
base_dir = Path(__file__).parent.parent
def update_details():
os.chdir(base_dir)
md_files = list(Path("docs").glob("**/*.md"))
# md_files = [Path("docs/advanced/decimal.md")]
re_str = r"<summary>((\n|.)*)</summary>"
# md_file = md_files[25]
for md_file in md_files:
content = md_file.read_text()
new_content = content
all_starts = re.finditer("<details>", content)
all_ends = re.finditer("</details>", content)
for start, end in zip(all_starts, all_ends):
sub_content = content[start.start() : end.end()]
m = re.search(re_str, sub_content)
assert m
summary = m.group(1).strip()
sub_content_internal = content[start.end() : end.start()].strip()
sub_content_no_summary = re.sub(re_str, "", sub_content_internal).strip()
new_sub_content = f"/// details | {summary}\n\n{sub_content_no_summary}\n\n///"
new_content = new_content.replace(sub_content, new_sub_content)
md_file.write_text(new_content)
if __name__ == "__main__":
update_details() |
Beta Was this translation helpful? Give feedback.
-
|
it would be cool to have one for tabs to close the gap ;) I will build a container image with those functions |
Beta Was this translation helpful? Give feedback.
-
|
Here it is https://github.com/hellt/pymdowx-block-converter Currently, I identified the following limitations:
ADD1: |
Beta Was this translation helpful? Give feedback.
-
|
@facelessuser and all, It is a common perception, that md table syntax is not particularly enjoyable not convenient to define tables. What if Blocks could come to the rescue? |
Beta Was this translation helpful? Give feedback.
-
|
This is technically doable already with the html block to some degree: import markdown
MD = """
/// html | table
//// html | thead
///// html | tr
////// html | th
**Fruit**
//////
////// html | th
**Description**
//////
/////
////
//// html | tbody
///// html | tr
////// html | td
**Banana**
//////
////// html | td
markdown: block
- Long
- Yellow
- Peelable skin
//////
/////
///// html | tr
////// html | td
**Apple**
//////
////// html | td
markdown: block
- Round
- Red
//////
/////
///// html | tr
////// html | td
**Orange**
//////
////// html | td
markdown: block
- Round
- Orange
//////
/////
////
///
"""
html = markdown.markdown(
MD,
extensions=['pymdownx.blocks.html'],
)
print(html)<table>
<thead>
<tr>
<th><strong>Fruit</strong></th>
<th><strong>Description</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Banana</strong></td>
<td>
<ul>
<li>Long</li>
<li>Yellow</li>
<li>Peelable skin</li>
</ul>
</td>
</tr>
<tr>
<td><strong>Apple</strong></td>
<td>
<ul>
<li>Round</li>
<li>Red</li>
</ul>
</td>
</tr>
<tr>
<td><strong>Orange</strong></td>
<td>
<ul>
<li>Round</li>
<li>Orange</li>
</ul>
</td>
</tr>
</tbody>
</table> |
Beta Was this translation helpful? Give feedback.
-
|
Thanks! It is a bit more convoluted than I anticipated, but it works way better for my use case than the original markdown syntax. Great work @facelessuser, you are the star. Here is how (and why) I use this: https://twitter.com/ntdvps/status/1747232825177219511 |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, I'm sure an extension tailored specifically to tables could be created. I was more saying you can get something "similar" to what is being asked, but obviously, it is a bit more cumbersome. I'm not sure if I specifically have an interest in creating a table-specific Block extension, but one could be created by an ambitious person 🙂. |
Beta Was this translation helpful? Give feedback.
-
|
Are there any known issues/limitations with indents/newlines in (un)ordered lists? I'm trying to display a warning admonition in an ordered list, but it either displays at the root level (Not indendet in the list) or doesn't render at all. As an example, using this: renders the admonition, but not with the proper indent While using this: doesn't render it at all I use SuperFences here, so indents should work fine to my knowledge... Anything else I need to look out for? |
Beta Was this translation helpful? Give feedback.
-
|
Well... The second example does exactly that. The text is indented 4 spaces which results in it not being parsed for some reason. Like. Try in your example without the gap between the block and the line itself, like I did. Pretty sure you encounter the same bug |
Beta Was this translation helpful? Give feedback.
-
|
Newlines matter |
Beta Was this translation helpful? Give feedback.
-
|
Yep, @hellt is correct, new lines matter. If a new line is not between the admonition block and the paragraph, the paragraph will gobble up the block as part of itself. |
Beta Was this translation helpful? Give feedback.
-
|
I guess... It still feels weird from a visual standpoint here... Like, this doesn't look good nor right for me (And probs other people using markdown): Like, this is needed to make it work properly. Not having an empty line after Three is causing the previously mentioned render proplems and not having an empty line after the admonition block causes the Four to be treated as nested line, resulting in This is oddly familiar to the behaviour of Python-Markdown's admonition blocks which also require empty lines arount them to properly render (At least I recall it like that)... |
Beta Was this translation helpful? Give feedback.
-
|
Python Markdown controls how blocks are handled, and Blocks are block extensions in Python Markdown so they behave like blocks. The only way to make sure that block A is separated from block B would be to scan all blocks for block B before the block A handler and break existing blocks up from each other. This is a huge pain as now you are playing a game of which extension runs first and trying to make sure you aren't stepping on the toes of other extensions. There are reasons for this logic. And I personally think that blocks should be separated from other blocks. That was the original intention of the original spec. It makes things more readable. And you don't run into issues where false blocks trigger premature breakage. I don't want to be writing a paragraph and have to worry that maybe my paragraph wrapping is going to trigger a new block. As for the new line at the end of lists, you are unfortunately confusing this as a Blocks problem, when Blocks is not the culprit for this behavior, it is Lists. When you start adding sub-blocks, you are no longer using "tight lists", so no, tight list behavior should not be expected. We can argue about whether a list item with multiple blocks should require a new line at the end -- and let me be clear, I am indifferent to whether lists require this or not -- but that is a wholly separate issue from Blocks. If you are asking me to "fix" lists, it isn't going to happen as this is not a list extension. Your issues are with Lists and they are not coming from this extension. I work within the framework of Python Markdown, this extension should not and will not alter lists. I don't control list new lines or list indentation in my extension, nor would it make any sense for me to do so. |
Beta Was this translation helpful? Give feedback.
-
|
Was there a fix for Blocks extension not being rendered in mkdocs-material when attrs contain not only classes but IDs as well? Here is a snippet that works And the one that doesn't render pymdown-extensions - 10.5 |
Beta Was this translation helpful? Give feedback.
-
|
Looking at the docs, the examples have |
Beta Was this translation helpful? Give feedback.
-
|
@Andre601 There was never a bug, I was just dumb and used a colon instead of a comma in the docs. This is what you should do: |
Beta Was this translation helpful? Give feedback.
-
|
I'll need to fix the docs |
Beta Was this translation helpful? Give feedback.
-
|
got it, thanks all! |
Beta Was this translation helpful? Give feedback.
-
|
I've found The equivalent tabs notation in the previous version didn't work with: As the image was not being shown and tabs got broken. Just something not working: For images, we are using the plugins Resuming: this new version will kill ;-) |
Beta Was this translation helpful? Give feedback.
-
|
There needs to be an empty line between the last option and the content: |
Beta Was this translation helpful? Give feedback.
-
|
Thank you. |
Beta Was this translation helpful? Give feedback.
-
|
I probably need to make this more explicitly clear in the docs, but @Andre601 is 100% correct, you must have a new line between the YAML config and the content. If there is no YAML config in the header, this new line can be omitted. |
Beta Was this translation helpful? Give feedback.
-
|
I knew, but as it was working I didn't bother about the new line. Also, forget about the issue with the |
Beta Was this translation helpful? Give feedback.
-
|
Can tabs be nested? What I'm trying: What I'm getting:
|
Beta Was this translation helpful? Give feedback.
-
|
This is covered in the documentation, so I would look that over, but short answer is yes, you have to differentiate them when nesting by using different number of |
Beta Was this translation helpful? Give feedback.
-
|
Solved! Amazing plugin. Thank you very much for your support. |
Beta Was this translation helpful? Give feedback.
-
|
Is this not redundant with the MkDocs Material syntax here? |
Beta Was this translation helpful? Give feedback.
-
|
I miss the |
Beta Was this translation helpful? Give feedback.
-
|
I've encountered an issue when using blocks (In my case the details one) with the The closing Reproducable example:
I cannot say if this is something to be fixed on your end or on the |
Beta Was this translation helpful? Give feedback.
-
|
The problem with the The block extensions, when parsed, attempt to gather the content of the entire block extension construct first to ensure it has a properly formatted block, and only if it acquires all of that is block content then parsed as Markdown. Since the default definition list extension grabs the header of the details block separately, and executes the parsing of it before the rest is acquired, it is not recognized as a complete block extension insert. The built-in admonition and definition list extension included in Python Markdown both behave this way and appear to unfortunately break blocks if they have new lines. Lists, on the other hand, another indented construct in Python Markdown, don't behave this way and never exhibit this problem. This could be fixed simply by having the built-in admonition and definition extension acquire the full content of a block first and then pass it on through the Markdown parser. This would be my preferred fix. They may disagree, and I don't know how difficult it is to pull this off yet, but It would definitely complicate block extensions if they could be parsed as block inserts before it is known if the block is complete (finding the end). This would not be something I would like to do. I think an issue could be opened here at least to let me explore the issue more, with that said, an alternative is to use the Pymdown Extensions implemented its own definition list extension as there are additional disadvantages using the built-in approach due to the forced indented format. For instance, using HTML with Anyway, if you are okay with using the Blocks version of definition lists, you avoid this issue as handling of such blocks is consistent. Otherwise, you would have to wait to see if someone, maybe me, gets around to and is allowed to apply such a fix to Python Markdown directly, or I come up with some solution here (possibly less likely). Below shows that the parsing works fine with both constructs are Blocks extensions. import markdown
MD = """
# Def list test
//// define
Definition 1
- Some text here
/// details | example
type: example
Lorem Ipsum Dolor sit amet
///
////
## Header to divide
//// define
Definition 2
- Another text here
/// details | example
type: example
Lorem Ipsum Dolor sit amet
///
////
"""
extensions = ['pymdownx.blocks.details', 'pymdownx.blocks.definition']
extension_configs = {}
print(markdown.markdown(MD, extensions=extensions, extension_configs=extension_configs))Results <h1>Def list test</h1>
<dl>
<dt>Definition 1</dt>
<dd>
<p>Some text here</p>
<details class="example">
<summary>example</summary>
<p>Lorem Ipsum Dolor sit amet</p>
</details>
</dd>
</dl>
<h2>Header to divide</h2>
<dl>
<dt>Definition 2</dt>
<dd>
<p>Another text here</p>
<details class="example">
<summary>example</summary>
<p>Lorem Ipsum Dolor sit amet</p>
</details>
</dd>
</dl> |
Beta Was this translation helpful? Give feedback.
-
|
Alright, thanks for the detailed explanation. If I get the time I'll see to open an issue on the python markdown repo to report this problem and hopefully get something going. |
Beta Was this translation helpful? Give feedback.
-
|
Just a heads up, this is a known issue that would require a major refactor of the entire block processor. I do not expect this to ever happen for the sole reason that I do not have the time to work on something that big. Unfortunately, I made a few poor design decisions years ago and we have been stuck with them ever since. |
Beta Was this translation helpful? Give feedback.
-
|
Yep, I totally understand. My main goal is to help people understand why the issue exists and how it can be worked around currently. If I'm able to come up with a way to make this work better in the built-in extensions, I'm open to it, but it will be dependent on me finding the time and a reasonable solution. I'm not sure it can easily be fixable at Blocks extension level. |
Beta Was this translation helpful? Give feedback.
-
|
I am searching for an inline/block delimiter that I can use in my MkDocs Material extension. I have two use cases where I am still looking for a good implementation:
This made me realize that the current delimiter isn't quite optimal. I cannot distinguish one-liners from blocks. Therefore, a start and end delimiter such as Some text {{{ latex | \textbf{ }}}bold in LaTeX only{{{ latex | }}}}Or for LaTeX blocks {{{ latex | \begin{something}
spam
}}} latex | \end{something}Not quite sure where I am going with this... |
Beta Was this translation helpful? Give feedback.
-
|
Beta Was this translation helpful? Give feedback.
-
Material content tabs (as currently documented) are based off the old Tabbed extensions, which was based off the Admonition syntax. It suffers from various issues that are described in this discussion. These new block approaches do not suffer from the same issues and are meant to be used in place of the old extensions, and maybe will replace them entirely at some point. |
Beta Was this translation helpful? Give feedback.
-
|
Not sure why, but code blocks aren't rendered inside details blocks? The ` are removed from the rendered page, but nothing else seems to change here. Here's the markdown file: https://github.com/DecentSoftware-eu/DecentHolograms-Wiki/blob/main/docs/general/actions.md?plain=1 And its corresponding, rendered page: https://wiki.decentholograms.eu/general/actions/ Edit: Nevermind... There are simply code blocks missing and it just so happens that I only checked those on the site.... Stupid me. |
Beta Was this translation helpful? Give feedback.
-
|
Block syntax nested under a list element with a list inside Hi all, is rendered as 
If we want to place the block under the list element with a list inside though, the syntax gets a bit weird with the closing 
Is there any escaping that needs to happen to support nested lists? |
Beta Was this translation helpful? Give feedback.
-
|
thank you for this extensive answer, @facelessuser, it is now clear what has happened and what is the recommended way considering the overarching Py Markdown rules. I loved the new Blocks syntax for its ability to write content without indenting it (which breaks syntax hl, makes pasting hard, etc). So I thought that I could've done the same with the Blocks under a list element, but now I see that it can't be like that. I will revert to the recommended version: Likely this is not possible, but I'd love to be able to do smth like this: But maybe this won't help anything =) |
Beta Was this translation helpful? Give feedback.
-
This cannot work because lists demand that each paragraph (and blocks) starts with an indentation. This is dictated by lists and is consistent across all Markdown parsers. How else would you know when a list ends? So you absolutely cannot unindent a block under a list and expect the list to just know you meant for it to be under it. |
Beta Was this translation helpful? Give feedback.
-
|
and last one, why then indenting the block ending marker breaks things? Is it because the nested list considers |
Beta Was this translation helpful? Give feedback.
-
|
In the unindented example, because blocks start to gobble up all Markdown until they find an end, it is possible that lists don't quite see what is going on when they encounter the below example. It is possible that the way Blocks works tricks lists into thinking the Block is a single block item. So it passes through and works, but is not intended to do so. The fact that this works is an unintended side effect that you've discovered and abused, but I don't think it is something that is worth fixing as it does behave in a fairly sane manner it seems. One thing to note though, indentation needs to be consistent according to Markdown rules. To answer your question as to why indenting the end The parser sees the opening A list with a nested |
Beta Was this translation helpful? Give feedback.
-
|
It is generally a good practice to always have content indented that should be on the same level as a list entry itself. If you dislike that it needs 4 indents and is therefore 1 space further right than the top entry, can you always add an extra space: <!-- This is valid -->
1. Lorem ipsum
/// info | dolor
sit amet
///
2. Another element. |
Beta Was this translation helpful? Give feedback.
-
|
I'm trying to build a blocks extension but I'm not sure it's the right approach. 😅 (sorry for the long post). I want to include multiple source file examples inline in multiple tabs in a summary, from a new block (?) with a config. Use CaseIn my docs I have some sections that include external files inline. For that I use mdx-include. Now, in many cases, I have several versions of the same file, with old syntax for Python 3.8+ and newer syntax in 3.9 and 3.10. I also have versions using So, it's a lot of different Python example files for the same example (a matrix of combinations). Then I include them in tab blocks. Here's an example from SQLModel: https://github.com/fastapi/sqlmodel/blob/1eb40b1f33aaebd02f03fd1986e242b65c79d573/docs/tutorial/fastapi/read-one.md#L17 Currently, I include some lines of the file (not the entire file). And then at the end, I include a details block with the entire file (in case people want to copy-paste or check the entire thing), I currently do this only in the SQLModel docs. I have been wanting to refactor it, to make it much less verbose to write in Markdown and automatize including the other versions (Python 3.10, 3.8, Annotated, etc). My idea is to have one main file shown and include only the specific lines for that file, the highlighted lines only for that file, and then have a details block below including tabs with all the versions, with the entire files. I imagine it could be something like this: /// include Then the (block?) extension would look for that source file to include, check what versions are there, include inline the highest version available of the file (e.g. Python 3.10 with Annotated), only with the lines specified, add a comment in between the included lines like I tried for a few days to follow the tutorials and read all the docs for extensions with the Markdown package, the pymdown blocks docs, and the docs for Maybe my whole approach is wrong, because maybe don't need a block that wraps content, only has metadata that is then used to include new content on the fly. I also see that mdx_include is a preprocessor instead of a block processor and maybe that's what I should be doing instead of trying to do it with the block processors, not really sure. Side note, do you do any freelance work @facelessuser? Would you be willing to help me out start this? If so, please contact me on my email (I didn't find a way to reach out to you). 🤓 |
Beta Was this translation helpful? Give feedback.
-
|
It's probably better that this has its own discussion, I've created one here: #2477 (comment) |
Beta Was this translation helpful? Give feedback.
-
|
Posted in wrong thread |
Beta Was this translation helpful? Give feedback.
-
9.10 introduces a new block extension type called Blocks. It provides a new generic block syntax inspired by reStructuredText Directives, but, while similar in some ways, they are different and should not be directly compared.
Blocks allow developers to more easily create special block containers for Markdown. In this release, we've actually reimplemented a number of plugins using the new Blocks approach: Tabbed and Details. We've also provided Blocks variants for Python Markdown's Admontions and Dictionary Lists. In addition, we've added a new HTML extension as well.
The aim of Blocks is to help eliminate the need for multiple levels of nesting when crating Markdown containers that nest. Additionally, it aims to provide a way to create new containers without having to constantly reinvent a new syntax that doesn't collide with other extensions.
Before, if we wanted to test some containers you could end up with something like this:
Now we can utilize the new Blocks extension to do:
Only Blocks that require raw content require the content to be indented code blocks, but they do not allow for nesting of other Blocks as raw content is ignored by the new Blocks extensions. Any Blocks extension that requires raw content will make that requirement known and under what circumstances.
Any and all feedback is welcome as this is a new experimental feature. While it is likely that no major changes will be made at this time, we are happy to hear if there are maybe some areas in which it could be improved.
Beta Was this translation helpful? Give feedback.
All reactions