data-copy for code blocks actually supports newlines

[iBug]

Description

This part of the documentation is misleading and missing information:

Note that this attribute does not support multiple lines, which is not a limitation of Material for MkDocs, but of the Markdown parser.

In fact, as long as new lines are HTML-encoded (i.e. 
), they stay perfectly intact when copied.

Additionally, if the value to data-copy contains braces, they must be HTML-encoded as well (i.e. { and }), or the Markdown parser breaks on that code block (which I actually suspect to be a bug - they're already inside double quotes).

It would be nice if these tips and quirks are noted in the documentation.

Basic reproduction:

``` { .c data-copy="int main() {
  return 0;
&#125" }
Try copying me for some C code
```

Related links

• Reporting a docs issue
• Code blocks / Code copy button

Proposed change

Remove the offending sentence and add the following text after the original paragraph and example:

Due to restrictions from the Markdown parser, newlines and braces must be
HTML-encoded, e.g. `
` and `{`. For example:

```` markdown title="Code block"
``` { .c data-copy="int main() {
  return 0;
&#125" }
Try copying me for some C code
```
````

<div class="result" markdown>

``` { .c data-copy="int main() &#123;&#10;  return 0;&#10;&#125" }
Try copying me for some C code
```

</div>

I couldn't work out a satisfactory replacement by myself, so this is just a suggestion. A better example is certainly welcome.

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[squidfunk]

Thanks for noting. However, encoding newlines as HTML entities is not something that we want to advertise on our documentation, as we need to keep it simple and concise. Please don't forget that many users are non-technical. Otherwise users will keep opening issues, asking how to achieve this, making more work for us with no upside for the project.

It's great that it's documented here now, but this feature is definitely something for advanced users. Note that it's also tagged as experimental, so if it turns out that it increases maintenance overhead for us, we might remove it again.

[squidfunk]

In fact, the braces problem almost leads me to the decision to remove it again. I did not know that. It seems just so impractical to use. Could I ask you to open an issue over at Python Markdown, to ask whether we could lift the restrictions on HTML entities? If regular verbatim code could be included, that would make up for much better usability.

[waylan]

What if the value to copy was in a separate code block? Consider this example:

``` { .c data-copy=unique-name }
Try copying me for some C code
```

``` { .c .unique-name .hidden }
int main() {
  return 0;
}
```

Any code block with the class hidden does not get displayed (a better name could be used here). And the value of data-copy points to the class of the code block which contains the text to copy. Or maybe the hidden class is unnecessary. Some JS could hide any block which is referenced by a data-copy attribute. In any event, I think something like this would be a much more useful implementation as it gives the user the freedom to control the entire block of text. If the user wanted to disable syntax highlighting for the copied text, they could add use_pygments=False as well.

[facelessuser]

That is indeed an interesting approach.

[iBug]

Just one small comment, @waylan. IDs ({#something}) look like a better option to me than classes ({.something}).

[squidfunk]

Interesting idea, definitely, but it's significantly more complicated from a theme developer's perspective. Nonetheless, it might be a much better idea than having to escape to HTML entities.

[waylan]

@iBug I agree, IDs would make more sense.

[squidfunk]

FYI, we removed this feature from our documentation. The current implementation is too fragile and will likely lead to many problems when being used by non-technical users. We don't feel comfortable providing support for it at the current stage.

[iBug]

With Python-Markdown/markdown#1414 being merged, the curly braces issue has been fixed. Other characters that has to be HTML-encoded still remains.