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 node `(org-transclusion)': (
C-h i and find the
Getting Started in the user manual will get you started in 5 minutes: online or Info node `(org-transclusion)Getting Started'.
For customization, refer to the customization group `org-transclusion' or user manual: online or Info node `(org-transclusion)Customizing'.
Here are 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/") :append)
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.3.0 - Feature :: - add: #145 a new property and filter to expand links to absolute file names (Org only) use :expand-links per transclusion - Fix :: - fix: #131. For non-Org files, now the transcluded text respects the indent level of the #+transclude keyword. This does not affect Org files. * 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.