pymdown-extensions
pymdown-extensions copied to clipboard
Per-snippet auto dedent
Description
While the "Dedent subsections" feature is nice to extract code that don't need the entire context around it, it requires all snippets to be dedented, which then causes issues elsewhere.
For now, my workaround is to just put a stripped down version of the code surrounding it, but this goes against the idea that the snippets are maintained elsewhere, not in the wiki itself.
Benefits
This would allow to select which snippets get dedented while not affecting other snippet
Solution Idea
I think that the existing global option would dedent all snippets, but not using the global option would let the user decide on each snippet, by adding an auto_dedent
next to the snippet lines/section
Example: --8<-- "https://github.com/freya022/BotCommands/raw/3.X/examples/src/main/kotlin/io/github/freya022/bot/commands/slash/SlashBan.kt:declare_aggregate-kotlin_dsl:auto_dedent"
I'm not sure I understand. The auto_dedent
option unindents content in subsections, which often are taken out of context of the rest of the file. They are still indented to a proper location within the target file. Can you provide a specific example demonstrating how there is an issue?
In one example, I am taking part of a JSON file's content, which I then surround to make a valid JSON file in the wiki:
In this case, the snippet has indentations, and I don't need dedentation, so this is fine.
Later, I needed to add a snippet that could be taken out of context, but since it has indents, I want to remove them, giving:
But now that I enabled dedendation, my JSON snippet is also dedented, giving:
So, currently, I need to keep dedentation disabled, and write the code surrounding the snippet, which becomes code that needs to be kept track of outside of the main repository
In general, Snippets was never meant to be an advanced template language. The entire idea was just a "dumb" way to insert content from one source to another. I can see how it can be frustrating because you are wanting in one case to manipulate the content knowing the context, but in the other case have the context of indentation stripped out.
Let me think about this and see if I can come up with an approach that I'm happy with. I don't think I'll go with the :auto_dedent
approach, but maybe I can come up with something that I don't dislike.
To be clear, I have most of my snippets in an actual project, so I can compile and run the program, which helps me know when I need to update my wiki.
Most of the code can be taken out of context, or already has no indents, so removing indentations makes sense.
However, when I add a snippet of a partial JSON object, I make sure the JSON is valid by surrounding the snippet with what's necessary. This is where removing indentations does not make sense, and this goes for anything that requires more context.
I currently have to disable the global auto dedent, as it would mess up a few snippets, hope you can see the issue:
Without context:
With context:
The context is quite irrelevant as:
- The reader already knows what the
database
variable refers to - The snippet also applies in a lot of different contexts
- The reader should be able to focus on the few lines that actually matter
As mentioned, I do see what you are aiming for, and I do understand what the cause is. As previously stated, this was always meant to be just a dumb, simple inserter, but, when I have the time, if I can come up with a syntax I'm happy with, we can have per snippet auto-indent.