GNU-devel ELPA - org-transclusion

org-transclusion Atom Feed

Transclude text content via links
org-transclusion- (.sig), 2024-May-20, 280 KiB
Noboru Ota <>
Browse ELPA's repository
CGit or Gitweb

To install this package from Emacs, use package-install or list-packages.

Full description


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 Org-transclusion node).

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'.

1. Example Use Cases & Main Features

Here are some real use cases that users have shared with the author, including his own.

Book writing
You have a collection of notes. You can quickly transclude paragraphs and sections from your notes and put together a draft. As transclusions are links, it's easy to re-organize them into different sequences to see which way works the best.
Academic writing
You have a collection of quotes and notes from your research and literature review. Transclude relevant elements of quotes and notes into different papers. You can keep your collection as the central repository of your research.
Technical writing
You write technical documents for software. Transclude relevant lines of code into the document. As the code is only transcluded, you can keep the document up-to-date as the code evolves.
Project status reports
You work on multiple projects at the same time and need to report to different project managers. Transclude relevant parts of your work notes and logs into respective project reports. You can keep a single collection of your work notes and logs.

Main Features:

  • Insert a copy of text content via a file link or ID link into an Org file
  • Work with any text file such as program source code, plain text, Markdown, or other Org files
  • With version 1.4, transclude content over network protocols like http:// (with org-transclusion-http) and hyper:// (with hyperdrive-org-transclusion). Splitting org-transclusion-add into two parts enables functions in org-transclusion-add-functions to be asynchronous.
  • Keep the file system clear of the copies of text content – Org-transclusion tries hard to save only the links to the file system
  • For Org files, use different headline levels from the source Org file
  • For Org files, use filters to include only relevant elements (e.g. filter out properties in the transclusions)
  • For program source and plain text files, transclude a certain lines or dynamically specify the from/to lines to keep the transclusion always up-to-date with the evolving source files
  • For program source files, transclude parts or whole code directly into Org's source block to leverage the rich Org features including noweb style syntax
  • Extend Org-transclusion with its extension framework

2. Installation

This package is available on:

  • GNU ELPA (releases only; equivalent to MELPA-Stable)
  • GNU-devel ELPA (unreleased development branch; equivalent to MELPA)

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" . "") :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 package-list-packages.

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
   :map global-map "<f12>" #'org-transclusion-add
   :prefix "n"
   :desc "Org Transclusion Mode" "t" #'org-transclusion-mode))

3. Contributing

  • Get involved in a discussion in Org-roam forum (the package is originally aimed for its users, the author included)
  • Create issues, discussion, and/or pull requests. All welcome.

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).

Thank you.

4. License

Org-transclusion is licensed under a GPLv3 license. For a full copy of the license, refer to LICENSE.

Old versions

org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB
org-transclusion- KiB


* 1.4.0 (2024-05-20)

  - Features ::

    Transclude content over network protocols like http:// (with
    org-transclusion-http: and
    hyper:// (with hyperdrive-org-transclusion:  Splitting
    org-transclusion-add into two parts enables functions in
    org-transclusion-add-functions to be asynchronous.

    - chg: #213 Allow making transclusion links from any protocol link
    - refactor: #209 Split -add-payload from -add to enable async transclusion

    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.

    add org-block-live-sync

    - Command 'org-transclusion-live-sync-start' now can start live sync

      1) transcluding a source code text file
      2) into org src block with the ':src' property in #+transclude

      Example: #+transclude: [[]]  :src python

    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

      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.

  - Fixes

    fix: #212 org-transclusion-make-from-link should not add
         transclusion link in next org heading

    fix: #211 Don't ever prompt to create a headline when transcluding

    docs: #210 Update docstring for org-transclusion-with-inhibit-read-only

    fix(src-lines): #219 Use end-pos in org-transclusion-content-range-of-lines

    fix(src-lines): #192 error when :thing-at-point nil

    fix: #174 add faces back org-transclusion and org-transclusion-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

    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

* 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