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
For installation and minimum configuration, refer to Installation below or the user manual: online or Info node `(org-transclusion)Installation'
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.
* Current development version - fix: add faces back org-transclusion and org-transclusion-source #174 - feat: add :things-at-point (or :thingatpt) property for transcluding source and other non-org text files. Both property names are synonym with each other and work in the same way. - feat: add org-block-live-sync - Command 'org-transclusion-live-sync-start' now can start live sync when 1) transcluding a source code text file 2) into org src block with the ':src' property in #+transclude Example: #+transclude: [[python-1.py]] :src python - feat: add org-transclusion-detach - New command 'org-transclusion-detach' can be used on the transclusion at point. It turns it into a normal, edtitable text content. You can undo this operation. In addition, you can press 'C-d' directly on the transclusion at point to detach it. This is because the command is bound to 'C-d' by default in 'org-transclusion-map'. - 'org-transclusion-refresh' now accepts universal argument such as 'C-u M-x org-transclusion-refresh' and detaches the transclusion at point. You can undo this operation. - 'org-transclusion-add' now accepts universal argument such as 'C-u M-x org-transclusion-add' and copies the source content rather than transclude it. You can undo this operation. - Limitation: Undo detach does not add the overlay back on the source. This should not break any feature. You can safely refresh the transclusion and recover the source overlay. You can also safely open or moved to the source. * 1.3.2 - fix: Delete superfluous trailing space on remove Before the fix, function 'org-transclusion-keyword-plist-to-string' would add a superfluous trailing space when converting #+transclude keyword's properties back to the string. This does not cause any harm in normal circumstances. The issue would occur with a rare combination of the case where: + You have a buffer with a large number of transclusions activated, around 50 or more + You set a 'whitespace-cleanup' in 'before-save' hook + You have 'auto-save-visited-mode' or similar that automatically saves a buffer If you had combination, and then saved the buffer with the transclusions, you might get an error mid-way of the save operation. You would not lose any data in the buffer, but the buffer would not re-activate all the transclusions that had been active before buffer-save. This was because of the superfluous trailing spaces and automatic removal of them, which caused the mismatch of the point of each transclusion that Org-transclusion remembered during the save operation. * Version 1.3.1 - build: fix #154 missing org-transclusion-pkg.el Nix requires -pkg.el. It was in ‘.elpaignore’. No functional change. * 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 ... ...