FR: Editable code blocks

[ofek]

Context

No response

Description

Sections of code blocks may be templated with default values and may be modified by clicking which transforms that area to a text box. New lines should not be supported inside the text boxes.

Related links

https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

Use Cases

This is useful when there is a desire for users to copy text or code and parts are defined by them.

Visuals

https://cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling#tag

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting. This was already asked before (can't find the issue right now, GitHub search, meh). Editing code blocks will mess with syntax highlighting, as we're doing highlighting during build time. When we would allow users to edit code blocks, the tokens entered wouldn't be highlighted. Additionally:

• I don't think there's much value in editing stuff without being able to execute it. When the user reloads the page, the changes will be gone, except for when we try to persist it, which is another challenge of its own.
• There are better solutions like for example markdown-exec by @pawamoy. It allows you to edit code blocks and execute them. If we would allow for editable code blocks, executing them is the logical next step, which is language-dependent and better left to third-party extensions. We have to cut scope wherever we can, trying to provide the best general documentation experience for users and authors while being open and flexible for extension.

For this reason, we consider this feature request out-of-scope. There are already better solutions! ☺️

[zswanson]

I don't think there's much value in editing stuff without being able to execute i

I disagree, we have a use-case for that. One of internal mkdocs site provides terraform samples that are built to help devs just copy/paste the most common configurations and only have to modify a things like adding the name of their app, their projectId etc, and so peristance or execution isn't a goal at all. We've written some javascript functions to help with this but having something built-in would be a lot better. The link to google cloud docs that @ofek provided are a perfect example of that capability - the 'code' isn't meant to be executed within the mkdocs site, its just so that you can fill in the values with some assistance and then copy/paste somewhere else.

There are better solutions like for example markdown-exec by @pawamoy. It allows you to edit code blocks and execute them.

Looks like you're referring to this part specifically? https://pawamoy.github.io/markdown-exec/usage/pyodide/
But that's a full editable code block whereas the suggestion here is specific editable 'words' in the block.

[squidfunk]

Thanks for providing the examples. I imagine that something like this can be implemented with a custom Markdown fence, but it would probably need language-specific support to denote what parts of the code block should be editable and what not. We here at Material for MkDocs, cannot provide this functionality, as it doesn't make a lot of sense for us to do so, because it needs minimal support from themes. If somebody implements something like this that is generic enough and doesn't only apply to specific languages, we're happy to the necessary support on the theme side!

[zswanson]

Sure, I only happened to find this issue while searching for a plugin that might provide this exact feature. :)

[squidfunk]

I think you'll rather need to implement a Markdown fence or extension, not a plugin, but I may be mistaken.

[samgaudet]

I would like to shamelessly self-promote an open source package (a custom fence) I created recently to solve this use case for anyone else who comes across this issue or is looking for this functionality: https://mkdocs-madlibs.readthedocs.io/en/latest/

Here's a sample:

[ofek]

Nice!