To install this package, run in Emacs:
M-x package-install RET org-transclusion RET
Org-transclusion lets you insert a copy of text content via a file link or ID link within an Org file. It lets you have the same content 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. Org-transclusion keeps your files clear of the transcluded copies, leaving only the links to the original content.
A complete user manual is available online or Emacs in-system as an Info document (
C-h i and find the
For installation and minimum configuration, refer to Installation below or the corresponding section in the user manual.
Getting Started in the user manual will get you started in 5 minutes.
Below are images and videos demonstrating some of the key features of Org-transclusion.
Figure 1. Animation to show creation of a transclusion from an ID link
Figure 2. Animation to show live sync from transclusion to source
Figure 3. Video demo on v0.2.1 on YouTube demonstrating new features to transclude a source file into a src-block and function to specify a range of text/source line
Here is a summary of some real use cases that users have shared with the author, including his own.
This package is available on:
GNU ELPA should be already set up in your Emacs by default. If you wish to add GNU-devel ELPA, simply add its URL to
package-archives like this:
(add-to-list 'package-archives '("gnu-devel" . "https://elpa.gnu.org/devel/") t)
Refresh the archive with
M-x package-refresh-contents RET and you can do
M-x package-install RET org-transclusion to install it. Alternatively, you can use
After installation, you can start using Org-transclusion with no additional configuration. Below are some example keybindings that can be put into your Emacs configuration.
(define-key global-map (kbd "<f12>") #'org-transclusion-add) (define-key global-map (kbd "C-n t") #'org-transclusion-mode)
For Doom users, you would need to do something like this below to install the package and configure the keybindings.
;; ~/.doom.d/package.el (package! org-transclusion)
;; ~/.doom.d/config.el (use-package! org-transclusion :after org :init (map! :map global-map "<f12>" #'org-transclusion-add :leader :prefix "n" :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))
Org-transclusion is part of GNU ELPA and thus copyrighted by the Free Software Foundation (FSF). This means that anyone who is making a substantive code contribution will need to "assign the copyright for your contributions to the FSF so that they can be included in GNU Emacs" (Org Mode website).
Org-transclusion is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.
* Version 1.2.0 - Feature :: - add: org-transclusion-after-add-hook - Fix :: - fix: org-transclusion-map now inherits org-mode-map (thanks to ag91 ) - fix: reverting 252ec675; shouldn't remove the extra space at the end of transclusions from Org - fix: #115 allow adding #+name, etc. before #+transclude keyword (don't remove affiliated keywords when org-transclusoin-remove) * Version 1.1.1 - Fix :: - Fix rare but destructive issue where buffer text content could be deleted by removing a transclusion. This could happen by killing a second Emacs instance (batch or online) or buffer, while the first Emacs keeps transclusions added - Other: - User Manual now refers to v1.1.x * Version 1.1.0 - Change :: - add:inhibit-read-only: fix:Org export errors with read-only With this, noweb expansion works now (limitation removed) - Fix :: - fix:#105 org-element--cache issue for Org v9.6 Remove use of silent-modificaiton & inhibit-modification-hook - fix:add-all not to stop with error in one trasclusion - fix:Remove extra space/line added to Org elements transcluded - Other :: - README, Info doc user manual, online user manual * Version 1.0.1 - Add .elpaignore - Bump up version only to enable ELPA; no functional changes * Version 1.0.0 - Initial version available on ELPA (https://elpa.gnu.org/) - Feature :: - =:end= property and a search term to dynamically define a range of lines to transclude for text and source code block - Change :: - Now user option =org-transclusion-include-first-section='s default value is changed to =t=. This seems to be more intuitive for more users - Fix :: - =org-transclusion-before-kill= now checks if the buffer to be killed contains any transclusion AND it is visting a file before saving. This fixes some issues related to temp buffers, etc. - fix: search options for src-lines extension for =:lines=, =:src=, and =:end= properties † Changes before Version 1.0.0 are in CHANGELOG file.