Embed external code via HTTP on an eleventy blog

| 2 min read

When I was writing my last article about generating a file without blocking form submission, I wanted to embed some code samples to explain the solution, but I wanted to avoid copy-pasting the code from the demo repository to the blog article. Inspired by Asciidoc partial inclusion, which I described in a previous article (in French), I decided to implement a similar method to retrieve some code via HTTP directly from a GitHub repo.

Well, I say "implement"... I should probably say "ask Chat GPT to do that for me." I wanted to see if the LLM could save me some time in implementing the solution. I thought the solution would be relatively easy to describe and create. I even created the prompt on my phone while commuting, just after having the idea. I tasked ChatGPT to build an Eleventy shortcode that takes a URL and a tag name, fetches the content, and returns the content between the start and end tags.

I had previous experiences where it took more time doing it with Chat GPT’s help than without it, but this time it wasn’t the case. Success on the first try, the generated code looked like what I imagined.

I tried the produced code when I was back on my laptop, and it worked. I just edited it a bit.

Here is the piece of code that you can include to configure 11ty in your .eleventy.js file:

 eleventyConfig.addAsyncShortcode("externalContent", async function(url, tag) {
// Fetch the content from the provided URL
const response = await fetch(url);
const text = await response.text();

// Define the start and end tags based on the input tag
const startTag = `// tag::${tag}[]`;
const endTag = `// end::${tag}[]`;

// Extract the content between the tags
const startIndex = text.indexOf(startTag) + startTag.length;
const endIndex = text.indexOf(endTag);

if (startIndex < 0 || endIndex < 0) {
throw Error(`Tag ${tag} not found in the document at ${url}`);

// Return the substring between start and end indices
return text.substring(startIndex, endIndex).trim();

And here is how you can use it with the new externalContent shortcode:

{% externalContent "https://gist.githubusercontent.com/SelrahcD/a0d1e2295f4195c51836e36b86b8232b/raw/a4d44b9ad70ca9595f149541b8d69a47574d64cf/somePHP.php", "MyCode" %}

// Code that is inside the MyCode tag block
$a += $a;

Which fetches the raw content for a file in a Gist and displays:

// Code that is inside the MyCode tag block
$a += $a;

Do you speak French and want to stop hating your tests ?

I've created a course to help developers to improve their automated tests.

I share ideas and technics to improve slow, flaky, failing for unexpected reason and hard to understand tests until they become tests we take joy to work with !

But you'll need to understand French...

You can even use that shortcode inside a code block:


{% externalContent "https://gist.githubusercontent.com/SelrahcD/a0d1e2295f4195c51836e36b86b8232b/raw/a4d44b9ad70ca9595f149541b8d69a47574d64cf/somePHP.php", "MyCode" %}


To get a nicely displayed PHP Code

// Code that is inside the MyCode tag block
$a += $a;

It’s a very raw solution and fand far from being quite as good as the Asciidoc implementation.
It deals only with comments starting with // and doesn’t handle tags inside tags.
But it’s good enough for my needs.

Maybe you and your team are trying to put some Living Documentation in place.
This is clearly one idea that you can use to generate documentation with code samples that stay up-to-date.
If you have some other needs around creating a documentation that moves along with you code, I probably can get you started. Let’s chat and see what happens next!