File-scoped namespacing for code block identifiers

[SamDuffield]

When using entangled with multiple markdown files that generate separate output files, I believe all code block identifiers share a global namespace? This means that common identifier names cannot be reused across different markdown files without causing code blocks to be mixed together in the generated output.

For example, if I have:
example1.md → generates example1.py
example2.md → generates example2.py

And both files have labelled #imports code blocks then both python files will have both #imports blocks. But I'd like them to only have their own one.

My current workaround is prefixing the code block names but I wonder if there's something more robust already supported? Or could be supported in future?

[jhidding]

Thanks for asking for this :) This feature has been on my mind from the beginning but I never got round to implementing it. I think for this to work there needs to be a namespace declaration in every markdown file. The most obvious place for such would be a YAML header at the top of a markdown file, like so:

---
entangled:
    namespace: example
---

We import NumPy:

``` {.python #imports}
import numpy as np
```

etc...

The Python code block in there can be reached from other places using a reference <<example.imports>>, but from inside the example namespace with just <<imports>>.

If no namespace is given there are two reasonable options: the file lives in global namespace or code-blocks are private. To be compatible with current behaviour, the default needs to be global, but an option can be added to set it to private.

This needs some deep changes in the data model. Also, there needs to be clarity about references being either absolute or unqualified. There is a possibility there to have ambiguity which we need to check against.

One way to organise the semantics around namespaces: if the root of a reference is not a known path in the global tree we prepend the local namespace to try again.

When stitching we need to decide how a reference is stitched back into the document. We know the global reference, but not how it was originally referenced. The user should accept that a fully qualified reference to a local code block will be replaced by a local reference on stitching.

[SamDuffield]

Oh so awesome adding this feature! Is it documented somewhere now how to configure the file-scoped namespace or more generally the YAML header?

[jhidding]

I'm still waiting for msgspec to release a new version that works on Python 3.14 to make a new release of Entangled. In the new release there will be an actual man-page. There will be a new homepage for Entangled and a bit more systematic documentation in the foreseeable future.

For now: You can configure two default settings, namespace_default, set to private or global. In private mode, the namespace of a code block will be the POSIX path of the source file. Global mode is the old behaviour.

Within each markdown source file you can manually set a namespace by setting namespace in the YAML header like so,

---
entangled:
    version: "2.4"
    namespace: aoc-day1
---

...

You can reference code blocks outside the current namespace by using :: as a separator:

``` {.python #blah}
<<aoc-day1::foo>>
```

You can use the YAML header to override any setting in entangled.toml, and if you have only one input file, you can even use just the header and leave out the toml config.

[SamDuffield]

Ah amazing this makes a lot of sense and significantly increase flexibility imo, thanks a bunch! Will look out for the new release