Optionally show the name of the file above the included file

[szabgab]

When I use my book for a presentation sometimes I need to jump to the source of the embedded file. For this having the name of the file above each (or most) embedded files would be nice. As I have several books with more than 10,000 embedded files, adding such snippets would be a lot of work and writing an external program to do that just sounds wrong.

It would be nice if I could set a global flag in the book.toml file to instruct embedify to show the name of the file above each file included using {% embed include file="" %}

Even better would be if the field could be used to describe what to show above each file. (e.g. using fields such as the

[preprocessor.embedify]
include.display_filename = "[{file}](https://github.com/szabgab/python.code-maven.com/tree/main/books/python-async/{file})"

Where the {file} is replaced by the valued in the "file" attribute of the "embed include" entries.

It should default to not showing anything at all.

---

Extra request:

I include both code-files (e.g .rs or .py extensions), but in many cases I also have files where I saved the output of a command and I include those files as well. So I have

{% embed include file="src/examples/async/src/demo.rs" %}

{% embed include file="src/examples/async/demo.out" %}

In this case I'd like to show the filenames only for the .rs files and not the .out files.
So maybe there could be a way to select (based on extension?) to which files the include.display_filename even applies.

e.g.

include.display_filename_filter = ["*.rs", "*.py"]

It might default to all the files.

[MR-Addict]

Can you give me some examples of your books. I'll take a look and do some improvements.

[szabgab]

My Rust books can be found here: https://rust.code-maven.com/ this is the source: https://github.com/szabgab/rust.code-maven.com/ They are in the books folder.

My older slides looked like this https://slides.code-maven.com/python/random-choice.html there you can see the included file and the filename above it that leads to the source code in GitHub.

[MR-Addict]

Okay, thank you!

[MR-Addict]

After some consideration, I realized that the previous request was a bit too specific.

To provide more flexibility, the new version adds additional information to the final rendered output. This allows you to write your own scripts to manipulate the DOM according to your specific needs.

You can download the latest release v0.2.18 to use this feature.

Below is an example script showing how you can use mdBook’s additional-js option to add custom logic for linking included files:

function linkIncludeFiles() {
  document.querySelectorAll("div[data-embedify][data-app='include']").forEach((node) => {
    const file = node.getAttribute("data-option-file");
    if (!file) return;

    // Only handle files inside src/examples/
    if (!file.startsWith("src/examples/")) return;

    // Only handle .rs and .py files
    if (!file.endsWith(".rs") && !file.endsWith(".py")) return;

    // Create a link to the corresponding GitHub file
    const a = document.createElement("a");
    a.href = `https://github.com/szabgab/python.code-maven.com/tree/main/books/python-async/${file}`;
    a.textContent = file;
    a.target = "_blank";

    // Insert the link after the current node
    node.insertAdjacentElement("afterend", a);
  });
}

document.addEventListener("DOMContentLoaded", linkIncludeFiles);

[szabgab]

Thanks for your quick resolution and sorry for the delay. Finally I had the time to try it.

I made some changes to make it easier to apply it to multiple mdbooks.
I have several books (more than 50) and I'd prefer not to copy and edit this file (setting the extensions and the base_url to every book.

const extensions = [".rs", ".py", ".toml"];
const base_url = "https://github.com/szabgab/rust.code-maven.com/tree/main/books/rust-programming/"

function linkIncludeFiles() {
  document.querySelectorAll("div[data-embedify][data-app='include']").forEach((node) => {
    const file = node.getAttribute("data-option-file");
    if (!file) return;

    // Only handle files inside src/examples/
    if (!file.startsWith("src/examples/")) return;

    extensions.forEach((ext) => {
        if (file.endsWith(ext)) {
            createLink(node, file);
            return;
        }
    });
  });
}

function createLink(node, file) {
    // Create a link to the corresponding GitHub file
    const a = document.createElement("a");
    a.href = `${base_url}${file}`;
    a.textContent = file;
    a.target = "_blank";

    node.insertAdjacentElement("afterend", a);
}

document.addEventListener("DOMContentLoaded", linkIncludeFiles);

[szabgab]

I made another change, splitting the "configuration" and the "code" into two js files:

book.toml has this:

[output.html]
additional-js = ["custom.js", "addlinks.js"]

custom.js:

const prefixes = ["src/examples/"];
const extensions = [".rs", ".py", ".toml"];
const base_url = "https://github.com/szabgab/rust.code-maven.com/tree/main/books/rust-programming/"

addlinks.js

function linkIncludeFiles() {
  document.querySelectorAll("div[data-embedify][data-app='include']").forEach((node) => {
    const file = node.getAttribute("data-option-file");
    if (!file) return;

    prefixes.forEach((prefix) => {
      if (file.startsWith(prefix)) {
        extensions.forEach((ext) => {
          if (file.endsWith(ext)) {
            createLink(node, file);
            return;
          }
        });
      }
    });
  });
}

function createLink(node, file) {
    // Create a link to the corresponding GitHub file
    const a = document.createElement("a");
    a.href = `${base_url}${file}`;
    a.textContent = file;
    a.target = "_blank";

    node.insertAdjacentElement("afterend", a);
}

document.addEventListener("DOMContentLoaded", linkIncludeFiles);

Could the javascript get the configuration date from the [preprocessor.embedify] section of the book.toml file?

See live here

[MR-Addict]

I’m afraid that won't be possible with the current architecture. The compiled JavaScript runs entirely in the client-side browser, which means it lacks access to book.toml. Because book.toml is a static configuration file used only during the build process, it isn't bundled or deployed with the production assets.

To move forward, I explicitly define the app extra metadata within the built book to ensure the app behavior can be personalized at runtime.

[MR-Addict]

Thanks for your quick resolution and sorry for the delay. Finally I had the time to try it.

I made some changes to make it easier to apply it to multiple mdbooks. I have several books (more than 50) and I'd prefer not to copy and edit this file (setting the extensions and the base_url to every book.

const extensions = [".rs", ".py", ".toml"];
const base_url = "https://github.com/szabgab/rust.code-maven.com/tree/main/books/rust-programming/"

function linkIncludeFiles() {
document.querySelectorAll("div[data-embedify][data-app='include']").forEach((node) => {
const file = node.getAttribute("data-option-file");
if (!file) return;

// Only handle files inside src/examples/
if (!file.startsWith("src/examples/")) return;

extensions.forEach((ext) => {
    if (file.endsWith(ext)) {
        createLink(node, file);
        return;
    }
});

});
}

function createLink(node, file) {
// Create a link to the corresponding GitHub file
const a = document.createElement("a");
a.href = ${base_url}${file};
a.textContent = file;
a.target = "_blank";

node.insertAdjacentElement("afterend", a);

}

document.addEventListener("DOMContentLoaded", linkIncludeFiles);

At this stage, I believe using custom JavaScript is the most viable approach.

Implementing a native solution for this use case would require users to configure several complex variables, including url_template, display patterns, file exclude patterns, various extensions, and filtering logic. Additionally, we would need to account for user-specific CSS styling requirements.

Introducing all these options into the core configuration would likely overcomplicate the experience for the average user. Custom JS provides the necessary flexibility without adding unnecessary overhead to the base setup.