Allow fetching code blocks from external source, display reference in code block title

[danielgafni]

Feature Request

Summary

I am writing a blog post which includes a lot of code blocks.

I would like to:

• associate a file name or a URL with every code block (or with most of them)
• ideally, place the source code in a separate file, potentially in a different repository

I tried searching for solutions, but was not able to find anything working.

Motivation

Such feature will allow to:

• Clearly present files corresponding to code blocks to the reader
• Make sure the code blocks are correct. It becomes possible to write tests and execute commands against the code block source code if it's separated from the page markdown body.

I believe this should be a very common problem for blog posts with heavy use of code.

Detailed Description

Perhaps, a code_block_source shortcode could be implemented, which could be used like this:

{{ code_block_source(source="https://my/file/url", language="python") }}

This shortcode would fetch the source contents, render it with syntax highlighting, and add a clickable source reference to the code block (I believe it can be shown before the copy button, or after the language title).

The source argument should accept both local paths and external URLs.

[welpo]

Hi!

Thanks for using tabi and for requesting this cool feature. I like the idea.

I've got a prototype shortcode which does exactly as you request.

Will update soon!

[danielgafni]

Amazing!

Thank you for writing Tabi :) I am really enjoying it.

[welpo]

Thank you! I'm glad to hear :)

The feature is added in #305.

It's almost exactly what you requested; to place the code in a code block, you need to add the backticks and language manually. This is necessary so that Zola can handle the syntax highlighting.

The docs should clarify the usage.

Let me know whether this works for your or if you encounter any issues!

Cheers

EDIT: Just realised I didn't add the "Show source" part. I'll think about how to implement this.

[danielgafni]

Thanks!

Yep, I was able to make something similar, but without the source reference, too.

I think it's an important part of this feature, it would be great if you could figure it out :)

[welpo]

Adding the source to the codeblock is easy enough with CSS. The challenge is making the URL clickable without JavaScript—I don't think it's possible.

Do you think this feature is important enough to warrant loading an extra (small) JS file?

Would it be enough to show the path/URL, even if it's not clickable?

[danielgafni]

I think we can start with just displaying it (can it have a copy button?) and add the other part later.

Honestly, my CSS/HTML/JS knowledge is close to zero, so I don't know what exactly has to be done to enable it.

[welpo]

Adding a "copy" option to the source would require JS too.

The thing is I'm not a big fan of JavaScript. The feature you are requesting is impossible to do without it, though, as we can't modify the HTML of codeblocks; Zola auto-renders them.

That's why I was asking how important the feature was. It's a simple enough change, so I'll add it soon.

[welpo]

Turns out it's not as easy.

• If we add the source to the code block (through the new shortcode), it gets rendered as code for the codeblock to show. That is, we can't just add a div or a span. I haven't found a way to escape this and actually render the HTML within the code block.
• Creating the HTML manually would allow this, but then we'd lose the syntax highlighting of Zola.

The only solution I see right now is to create another shortcode like add_src_to_codeblock. This will take a single argument, the src. Then a JavaScript file would match each src added by the shortcode to the next codeblock it finds.

This means adding two shortcodes per codeblock with visible source, in the right order, with the same data. Plus, loading the JS file to handle the "joining" of data.

[welpo]

It works, though.

(The URL is clickable.)

I just need to write the docs.

[danielgafni]

Alright, great!

Do you think we should also have an option to override the displayed source path with something else?

For example, the desired file location could be displayed instead of the original source path, indicating that this code block contents should be placed in the desired path.

[welpo]

Do you think we should also have an option to override the displayed source path with something else?

The src for the codeblock and the src for the text (what's shown in the code block) are independent. So you would do:

{{ add_src_to_codeblock(src="https://example.com/whateverURL") }}

```.gitignore
{{ remote_text(src="https://example.com/the_actual_url.py") }}

[welpo]

It's done in #307.

Not a fan of the JavaScript + shortcode + shortcode setup, but it's the best we can do given the constraints.

Check out the documentation and give it a go! Let me know whether it works for you or if you encounter any issues.

Cheers

[danielgafni]

Thanks, looking great!

The only small issue I found is with formatting with a long url and a small screen.

[welpo]

Thanks for letting me know! Should be fixed with f081a92f5939e141b6dbd7afe8ad1a9519d47f30