org-transclusion: one Org source, many buffers, no copy and paste

Copies in the buffer, links on disk

org-transclusion lets you insert a copy of text content into an Org file via a file link or an ID link. The description of what that buys you is precise: the same content can be present in different buffers at the same time without copy-and-pasting it. Edit the source of the content and you can refresh the transcluded copies to the up-to-date state. And the point that makes the package interesting is that Org-transclusion keeps your files clear of the transcluded copies, leaving only the links to the original content.

That last sentence is the design decision everything else follows from. A naive implementation would write the copied text into the file, which means the file is now wrong the moment the source changes, and you have two copies of the same paragraph in your notes directory with no way to tell which one is authoritative. Here, the file on disk holds a link, and the copy exists only in the buffer. The document you read in Emacs shows the content, and the document stored on disk stays a small pointer.

The source can be any text file, not just another Org file. Program source code, plain text, Markdown and other Org files all work, and the same content can be present in several buffers at once, which is the case the package was built for. The use cases the README lists are all instances of that pattern. A book writer has notes and transcludes paragraphs into a draft, and because the transclusions are links, they can be re-sequenced easily to try a different order. An academic writer keeps a central repository of quotes and transcludes the relevant ones into different papers. A technical writer transcludes lines of code into a document so the document stays current as the code evolves. And a project manager juggling several projects transcludes from one collection of work notes into separate reports.

Org specific power: headline levels, filters and line ranges

The features that go beyond plain inclusion are the ones that make transclusion usable in a real Org workflow.

For Org files, you can use a different headline level from the source Org file, which solves a genuine problem. A section that is a top level heading in your notes is usually a subsection in a chapter, and without this the structure of the assembled document would be wrong. You can also use filters to include only relevant elements, and the example given is filtering out the properties in the transclusions, which is a small thing that removes visible noise from every included block.

For program source and plain text files, you can transclude a certain range of lines, or dynamically specify the from and to lines so the transclusion stays current as the source file evolves. The dynamic form is the one that matters for technical writing, because a hard coded line range breaks the moment you add a line above it. The documentation also shows transcluding parts or whole code directly into an Org source block, which lets you use the rich Org features there, including noweb style syntax.

Then there is the extension framework, which lets you extend org-transclusion itself. The code is split across several files, with org-transclusion.el as the main package and separate files for the transient menu, the HTML export, the font lock, the indent mode and the src line handling, plus text-clone.el for the text cloning. Since the extension points are the package's own function names, a customiser works in the same idiom as the package rather than around it.

Installing from GNU ELPA and the first five minutes

The package is available on two archives. GNU ELPA carries the releases only, and is described as equivalent to MELPA-Stable, and GNU-devel ELPA carries the unreleased development branch, equivalent to MELPA. GNU ELPA is already set up in Emacs by default, so for the release version there is nothing to configure. To add the development archive you add its URL to package-archives.

(add-to-list 'package-archives
             '("gnu-devel" . "https://elpa.gnu.org/devel/") :append)

Then refresh the archive and install the package.

M-x package-refresh-contents RET
M-x package-install RET org-transclusion

The documentation notes that package-list-packages works as an alternative to the install command. After installation you can start using org-transclusion with no additional configuration, and the README offers a set of example keybindings you can put into your Emacs configuration.

(define-key global-map (kbd "<f12>") #'org-transclusion-add)
(define-key global-map (kbd "C-n t m") #'org-transclusion-transient-menu)
(define-key global-map (kbd "C-n t t") #'org-transclusion-mode)

There is an alternative with use-package in the same section, for people who configure Emacs that way. A complete user manual is available online at the project homepage and as an Info node inside Emacs, reachable with C-h i and searching for Org-transclusion, and the manual has separate sections for installation, getting started and customizing, with the customization group named org-transclusion. The README says the getting started material gets you going in five minutes.

Network sources and asynchronous functions in version 1.4

The feature list mentions that with version 1.4 you can transclude content over network protocols such as http:// with the org-transclusion-http package and hyper:// with the hyperdrive-org-transclusion package. It also explains a structural consequence of that, that splitting org-transclusion-add into two parts enables functions in org-transclusion-add-functions to be asynchronous.

That is a notable design move for an Emacs package, and it is worth being careful about the version numbers here. The release list in the repository shows v1.3.0 tagged on 2022-06-12, v1.2.0 in January 2022 and v1.1.1 in December 2021, so the 1.4 capability described in the README is ahead of the newest tagged release in the list, which is the situation you would expect from a package whose development branch is where the new work lands. If you want the network transclusion, the development archive is the place to look, and the two external packages are separate dependencies with their own upstream repositories.

The repository layout also shows how the documentation itself is built. The Makefile has a rule that generates the manual source from the manual Org file by running org-transclusion-add-all in batch mode and writing the result out, which means the manual is itself assembled from transcluded parts. The README-elpa target exports the README to plain ASCII for the ELPA package description, and there are targets for byte compiling the sources, checking declare-function calls, and cleaning. The test target compiles the package and cleans, and there is a test/ directory and a text-clone-docs/ directory in the tree.

Where org-transclusion is the wrong tool

Three cases argue against it. The first is a workflow where the copies must be editable independently. The model is that a transclusion is refreshed from its source, so if you want a passage to diverge from the original, this package is the wrong instrument and you want a copy. A package that supported branching, where a transclusion could be detached and diverge while keeping a link back to where it came from, would be a different design, and the README does not describe one. The second case is a team not using Emacs. There is no non-Emacs implementation mentioned, and the extension framework, the transient menu and the font lock integration are all Emacs concepts, so this is a package for people who already live in Org Mode.

The third case is a large collection of notes with heavy cross linking, and the reason is a structural one. Every transclusion is a dependency on a file, and the source files carry the identity of the transclusions through their IDs. The filtering and line range features work by the source cooperating with the transclusion, and the ID link mechanism is how a transclusion finds its source. That is workable, and the package is careful about it, but it means the relationship between your files becomes load bearing in a way that ordinary Org links are not. If you restructure your notes directory, the transclusions that point into it are the thing that breaks.

On the practical side, the repository is not archived and the last push was on 2026-04-17, but the newest tagged release is v1.3.0 from 2022-06-12, which means the stable channel is old and the newer capabilities live on the development archive. The project is GPL-3.0 licensed, which is unremarkable for an Emacs package, and it is published on GNU ELPA, so the package is signed and installable through the standard package mechanism rather than from a raw repository.

Editorial conclusion

org-transclusion suits an Org user with one collection of notes who assembles several documents from it, especially for technical writing where code excerpts need to track the source, and it installs from GNU ELPA with no configuration required. It does not suit someone who wants the copies to be editable independently of the source, because the whole model is that they are refreshed from the source, and it does not suit a note-taking setup outside Emacs, since the implementation is an Org Mode package with an extension framework of its own. Before you adopt it, decide where your canonical content lives, because every transclusion is a dependency on that file, and note that the last push was on 2026-04-17 with the newest tagged release at v1.3.0 from 2022-06-12.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. nobiot/org-transclusion on GitHub
3. Project website
4. README
5. Releases