Code boxes: Allow users to add their own vars on the rendered site

squidfunk / mkdocs-material

Documentation that simply works

https://squidfunk.github.io/mkdocs-material/

MIT License

20.46k stars 3.49k forks source link

Code boxes: Allow users to add their own vars on the rendered site #4332

Closed userbradley closed 2 years ago

userbradley commented 2 years ago

Contribution guidelines

[X] I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

[X] ... to my best knowledge, my idea wouldn't break something for other users
[X] ... the documentation does not mention anything about my idea
[X] ... there are no open or closed issues that are related to my idea

Description

Allow users to add their own values to code boxes across a page, so they can set values once and all subsequent boxes on that page will have their values filled out

Use Cases

I am explaining how to enable IAP on a google cloud project, and it would be nice to have the users simply provide their project and compute engine name once, and all subsequent code boxes have that information updated

Screenshots / Mockups

Example of what it could look like with no input

Example of adding user input

Google do this well: https://cloud.google.com/kubernetes-engine/docs/how-to/internal-load-balancing-across-vpc-net

squidfunk commented 2 years ago

Thanks for suggesting. Interesting idea. The problem is that we'd need to find a representation for placeholders that works in all programming languages. Material for MkDocs is agnostic, so we need to find a way to generate code snippets that we can easily consume in the frontend after they were passed through Pygments.

Furthermore, we must find a representation that works without JavaScript. @facelessuser maybe has an idea how this could be pulled off from a Markdown extension perspective. Maybe with a custom fence that does some preprocessing before passing stuff to Pygments?

Code annotations are related, as they use the comments of a language for placement. For variable placement, a much more sophisticated logic would be needed. Let's let this idea sit for a while and see whether other users would find this useful.

facelessuser commented 2 years ago

Yeah, almost anything could be done with a custom fence, but I imagine a working solution via this method would be non-trivial. The biggest issue is getting something that works with Pygments. I won't comment at this time as to how difficult that would be as I have not looked at all into something like this. I assume if someone was motivated enough that it might be doable 🤷🏻.

squidfunk commented 2 years ago

I've investigated this feature request and think it's currently too big of a problem to be solved for all languages. In general, it might be solvable similarly to code annotations, which use comments (.c, .c1 or .cm) in the source language for marker placement, but variables are a much, much harder problem to solve. The reason is that there's no canonical lexeme or pattern that is output by Pygments that can be used to identify variable markers. Thus, marker identification would probably need to be implemented as a preprocessor to Pygments, but I personally think that it's a huge task to make this work for all languages and in a simple way with good DX. I might re-evaluate this in the future, but currently, I'll consider it out-of-scope.

userbradley commented 2 years ago

Appreciate the effort on this one! I feel like this is more of a full fledged CMS type of thing!

kvanzuijlen commented 7 months ago

Google has some interesting documentation for their implementation: https://developers.google.com/style/placeholders. Might be handy if/when this functionality gets reconsidered.

userbradley commented 7 months ago

Agreed, I once found the python package they use but since can't find it!

I need to have a look again I think

I'd love for this to be implemented in some sort, it would make my documentation a lot cleaner

kvanzuijlen commented 7 months ago

As far as I can tell they're using Eleventy with some proprietary (markdown-it) plugin sadly 😞

EDIT: This is the (minified) JavaScript they're using: www.gstatic.com/devrel-devsite/prod/v50a9748f336f0601961fb23638b43fbbc8f87f50f5f0aa83e2751247a72fbd3b/cloud/js/devsite_devsite_var_module.js

squidfunk commented 7 months ago

I currently have no bandwidth to come up with a solution from scratch, but if somebody finds a Markdown extension or plugin that implements this, I'd be happy to look into how they did it and if we can adapt or port it to Material for MkDocs.