Include a file name for code blocks

[Xenonym]

Tell us about your environment

• MarkBind Version: 1.17.1

Rationale: Developer documentation usually includes not only code excerpts, but also sample code files. It can be a nice visual reminder for the reader if we include the file name for a given sample code block, especially if that code file needs to have a fixed name (eg. configuration files like .travis.yml).

Example: From Travis CI documentation:

[damithc]

That's a good idea, although we probably shouldn't use a whole new line for it. i wonder if we could/should include a download button to go with the file name.

[Xenonym]

That's a good idea, although we probably shouldn't use a whole new line for it.

How about in the lower right corner? Having the file name in the same position with the text might mess up copy-pasting though.

I wonder if we could/should include a download button to go with the file name.

Generating a download via JS is technically possible, see FileSaver.js. Unlike #629, this should definitely be optional, since there probably isn't any value in downloading small code excerpts.

[damithc]

How about in the lower right corner? Having the file name in the same position with the text might mess up copy-pasting though.

Perhaps it is OK to do it as in the screenshot, as the filename is going to be optional and will not be present in most cases.

Generating a download via JS is technically possible, see FileSaver.js. Unlike #629, this should definitely be optional, since there probably isn't any value in downloading small code excerpts.

Yes, that should be optional too, only for cases where the user is meant to save the file locally and do something with it. In fact, probably should be a very low priority feature, if we are going to do it at all.

[nbriannl]

Hi, I'm interested in picking this up. Can I clarify if by 'code block' you mean https://markbind.org/userGuide/formattingContents.html#code ? This also applies to #646

[damithc]

Hi, I'm interested in picking this up. Can I clarify if by 'code block' you mean https://markbind.org/userGuide/formattingContents.html#code ? This also applies to #646

Yes for both.

[damithc]

Also, should we generalize this beyond filenames? There might be other information the author might want to show e.g., before and after.

[damithc]

If we make this a general heading feature (similar to box headings), we might not even need #646

While it is a bit of extra work, authors can show the code language by simply adding a heading.

[yamgent]

If we make this a general heading feature (similar to box headings), we might not even need #646

Good idea, @nbriannl what do you think? Since with #646 authors must specify whether to have the indicator enabled or not, I think we might as well just let the authors be able to customize the content of the heading entirely.

[nbriannl]

@yamgent I agree completely. Current working on #1020

[damithc]

@nbriannl this issue is done, right?