Per-snippet auto dedent

[freya022]

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"

[facelessuser]

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?

[freya022]

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

[facelessuser]

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.

[freya022]

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

[facelessuser]

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.

[shaedrich]

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.

We have a similar problem, but I don't think, there's a need to discuss whether it's a dumb or an intelligent templating language or whatever this is. I think, the whole point of the issue is: There are different kinds of files and for some, one wants auto dedention and for some, one doesn't, meaning, there needs to be a local option additionally to the global one.

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.

Other options might include:

• Making dedent_subsections option bool|{string:bool} with the latter being an option to define sub folders to base_path where you want or don't want auto dedention → only works when sub folders are used:

  markdown_extensions:
  - pymdownx.highlight
  - pymdownx.snippets:
    base_path: ['snippets']
    dedent_subsections:
      auto_dedentable: true
      non_auto_dedentable: false

• Making it an option of the fence (like line numbers or highlighting lines), rather than the snippet part → not entirely intuitive, let alone, I'm not sure Whether the implementation details would even allow for that option

  ```{.json dedent_subsections=false}
  --8<-- "my_json_file.json:40:42"

• Similar to the previous option, but part of the block format (would also work with other option like manually setting the indention base level or preserve_tabs) → only works for block format, but could also be done with a single snippet within a block as a workaround

  ```json
  --8<-- dedent_subsections=false
  my_json_file.json:40:42
  --8<--

• Moving the marker to the prefix, for example
  • --8<--: auto dedention
  • --8>--: no auto dedention or
  • --8<--: auto dedention
  • -->8--: no auto dedention

[facelessuser]

We have a similar problem, but I don't think, there's a need to discuss whether it's a dumb or an intelligent templating language or whatever this is.

My providing of context as to my goals for the extension and providing context as to why I want to limit the scope of the plugin are perfectly relevant. With that said, I've also already given my statement. If/when I come up with a syntax I'm happy with, I will implement it.

Making it an option of the fence (like line numbers or highlighting lines), rather than the snippet part → not entirely intuitive, let alone, I'm not sure Whether the implementation details would even allow for that option

This ties snippets to the code block extensions. It is separate from that , so such interaction will not be supported. Snippets is a preprocessor run before code blocks so code blocks knowledge of whether specific lines are snippets or not will be lost. This is a non-starter.

Similar to the previous option, but part of the block format → only works for block format

This is limited to block format, but something to consider. Most likely I will extend the syntax in some form that works for both blocks and inline.

Moving the marker to the prefix, for example

I probably won't go in this direction, but there may be some additional syntax we can add moving forward.