Download button for code blocks

[joapuiib]

Hello!

I am constantly adding files to my documentation in this way:

\```java
--8<-- "docs/path/to/file"
\```

I would love to have a Download button in code blocks, similar to Code Copy Button.

[squidfunk]

Thanks for suggesting! This is an excellent use case for a third party extension ☺️ The tricky part will be resolving the file URLs, as they can point anywhere in the repository, e.g., outside of the docs directory, which means the files need to be explicitly copied to the build directory, or point to a valid URL on GitHub, if the repository is hosted there. It's not trivial, but definitely possible to pull off! If you decide to follow this path, feel free to share your results here! 🚀

[joapuiib]

In order to address this, I need to know which would be the best approach.

My initial thought was to add an attribute (download in this example, but could be any) telling the relative path of the file using attr_list.

\```java
--8<-- "docs/path/to/file"
\```
{download="../../path/to/file"}

Note

Files should exist in the docs directory and the path should be a relative to the current page. AFAIK MkDocs doesn't allow absolute urls.

AFAIK, the Code Copy Button is generated automatically with JavaScript. I thought that maybe this theme could do the same with <code> blocks that have a download attribute.

It would be nice to have a good integration with this theme, specially in styling the download button and have a tooltip similar to copy button.

---

If this approach is feasible, the next step would be to set the download attribute automatically, so it's easier to use.

In that case, I think a MkDocs plugin could do the trick, since it knows the path of each page and can compute the relative path to the file. In this case, also using files outside docs could be achieved.

[facelessuser]

Do you want to download the file or download the text in the code block? I suspect downloading the content in the code block is sufficient and could be accomplished without worrying about paths.

[joapuiib]

In my case, there's no difference between the content of the code block and the content of the file, so it doesn't matter.

A possible use case could be to just show a part of the file in the codeblock, but the whole file is downloaded.

[facelessuser]

You can attach a data-* attribute and trigger off that. Use Javascript to add a button to all blocks with that data attribute.

```lang {data-download="1"}
Content
```

If you only need the code content, the JS can simply download that.

If you want to link a file, if your file content is not included in your documentation (which quite often is the case) use an full URL and the JS can just create the button as a link with the download attribute: https://www.w3schools.com/tags/att_a_download.asp.

```lang {data-download="https://github.com/user/project/blob/main/project/file.ext"}
Content
```

You could create a custom fence that injects the button without JS via custom fences in SuperFences. Granted, most of these cases require you to get your hands a little dirty and do some coding. If that's not an option, then you'd have to get someone to add a feature here.

[kamilkrzyskow]

I would also go with the code block content approach. The Highlight extension also provides the option to add the lang name pygments_lang_class, which could be used for deciding on the extension of the downloaded file, or use the data-download= as the container to hold the filename containing the extension.

[joapuiib]

I like @facelessuser approach:

• data-download="1": Download the code block content:
  • Challenge: Compute the download filename. Maybe we can use title or another data-* attribute.
• data-download=url: Create a link button with a download attribute.

---

This would be achieved with JS, so I guess just an extra_javascript is needed.

I'll start to work on a prototype.

[joapuiib]

Also, the download button positioning is not optimal.

I've noticed that Code selection button uses a md-code__nav element to wrap all md-code__button in order to position them correctly one next to the other.

I would need to place the download button inside the button toolbar, but I can't control when the toolbar is rendered. Also, I don't even know if that is released to the public or just to insiders.

[squidfunk]

We currently have no time or plans to ship something like this, no, as we basically have a feature freeze right now. We're working on fundamental changes, so we can't invest time in things like button placement. I hope for your understanding.

[joapuiib]

My comment was not a request for you to implement it, just consideration about including a feature that I think could be useful. I understand you are working on bigger things.

I wanted to gather information about how to approach this (thanks @facelessuser and @kamilkrzyskow for your insights) and show the challenges I faced while writing this.

I just wanted to show that I don't see a good way to fully integrate it with Material for MkDocs as a 3rd party extension, and I think it wouldn't be difficult to implement it in this theme source code.

I don't mind working on this. If you think this feature is interesting, I can try to implement it in this theme with some guidance.

[squidfunk]

As said, we're currently in feature freeze. We can look into this next year ☺️

[joapuiib]

Sure. Let me know if I can help with anything.