/org-transclusion-power-pack

Enhancements for org-transclusion: Toggle transclusions with a single keystroke, seamlessly add org-roam nodes as transclusions, match transclusions to the current org-heading level, and more intuitive function names for easier navigation.

Primary LanguageEmacs Lisp

Introduction

A suite of enhancements for the Emacs package `org-transclusion`, which allows you to dynamically display content from one org file in another.

Enhancements include:

  • toggle transclusions on and off with a single keystroke
  • a function to add an org-roam node as a transclusion
  • a function to add transclusion and match current org-heading level
  • more intuitive function names for easier navigation

Prerequisites

  • Emacs version 28 or higher
  • Org-mode version 9 or higher
  • org-transclusion package

Installation

  1. Ensure that `org-transclusion` is installed and properly configured in your Emacs.
  2. Clone/download the enhancements from [repository URL].
  3. Add the following lines to your Emacs configuration:

(load “path/to/enhancements.el”)

  1. Restart Emacs to apply the changes.

Org-transclusion Power Pack

Enhanced Functionality

Toggle Transclusion

  • Function: `tr-toggle-transclusion`
  • Description: Toggle transclusion on or off with a single keystroke. If the point is on a line starting with `#+transclude:`, it expands it. If the point is on a transclusion, it collapses it.
  • Usage: Use this function to quickly toggle transclusions without having to determine whether you’re expanding or collapsing transclusion states.

Alias Definitions

  • Aliases:
    • `tr-expand` for `org-transclusion-add`
    • `tr-collapse` for `org-transclusion-remove`
    • `tr-make-link` for `org-transclusion-make-from-link`
    • `tr-expand-or-collapse` for `org-transclusion-add-or-remove`
  • Description: Provides shorter and more intuitive command names as aliases to the existing transclusion commands, simplifying recall.

Insert Transclusion Links

  • Function: `tr-insert-transclusion`
  • Description: Inserts transclusion links by integrating with `org-roam-node-insert`. Automatically prepends `#+transclude:` to the links.

Insert Transclusion Links with Matched Heading Level

  • Function: `tr-insert-transclusion-match-level`
  • Description: Inserts a transclusion link via `org-roam-node-insert` and adjusts the heading level to match the current context, ensuring seamless document structure integration.
  • Usage: Ideal for users who want to maintain consistent heading levels across transcluded sections, enhancing the document’s organization and readability.

Convert Link to Transclusion

  • Function: `tr-convert-link-to-transclusion`
  • Description: Converts an existing Org-mode or Org-roam link at the cursor position into a transclusion link by prepending the `#+transclude:` directive.
  • Usage: Useful for quickly transforming regular links into dynamic content embeddings, simplifying the workflow for document assembly.

Convert Link to Transclusion with Matched Heading Level

  • Function: `tr-convert-link-to-transclusion-match-level`
  • Description: Similar to `tr-convert-link-to-transclusion`, but also appends a `:level` directive to match the current heading level, ensuring that the transcluded content aligns perfectly with the surrounding structure.
  • Usage: Best suited for complex documents where maintaining a consistent heading hierarchy is crucial for readability and navigation.

These enhancements are designed to make working with transclusions in Org documents not only more powerful but also more intuitive. By simplifying and automating common tasks, they allow users to focus more on content creation and less on manual formatting.