[org] add support for transclusion (#15333)

Co-authored-by: Lucius Hu <lebensterben@users.noreply.github.com>

CHANGELOG.develop

@@ -2889,6 +2889,8 @@ files (thanks to Daniel Nicolai)
 - Fixed ocamlformat not properly initialized by following do (thanks to Nicolas Raymond)
 - Allow new OPAM share commandline syntax (thanks to Cody McKenzie)
 **** Org
+- Add initial =org-transclusion= support behind =org-enable-transclusion-support=
+  flag (thanks to Keith Pinson).
 - When =org-appear= is set to be triggered manually and Spacemacs' editing mode is
   Vim or hybrid, register relevant =org-appear= commands in Evil hooks for Org
   buffers (thanks to Keith Pinson).

layers/+emacs/org/README.org

@@ -35,6 +35,7 @@
   - [[#jira-support][Jira support]]
   - [[#valign-support][Valign support]]
   - [[#org-appear-support][Org-appear support]]
+  - [[#transclusion-support][Transclusion support]]
   - [[#verb-support][Verb support]]
   - [[#asciidoc-support][AsciiDoc support]]
   - [[#spacemacs-layout-integration][Spacemacs layout integration]]
@@ -70,6 +71,7 @@
     - [[#verb-response-body-mode-bindings][Verb-response-body-mode bindings]]
     - [[#verb-response-headers-mode-bindings][Verb-response-headers-mode bindings]]
   - [[#org-roam][Org-roam]]
+  - [[#transclusion][Transclusion]]
 
 * Description
 This layer enables [[http://orgmode.org/][org mode]] for Spacemacs.
@@ -84,6 +86,7 @@ This layer enables [[http://orgmode.org/][org mode]] for Spacemacs.
 - Easy insert of URLs from clipboard with org format via [[https://github.com/rexim/org-cliplink][org-cliplink]]
 - Rich insert of code (into a source block with highlighting, and a link) from other buffers via [[https://github.com/unhammer/org-rich-yank][org-rich-yank]]
 - Pixel-perfect visual alignment for Org and Markdown tables via [[https://github.com/casouri/valign][valign]]
+- Text transclusion via [[https://nobiot.github.io/org-transclusion][org-transclusion]]
 
 * BibTeX
 For more extensive support of references through BibTeX files, have a look at
@@ -551,6 +554,15 @@ To install [[https://github.com/awth13/org-appear][org-appear]], which toggles v
 If you set =org-appear-trigger= to =manual= and your editing style is =vim= or =hybrid=,
 =org-appear= is turned on in insert mode but not in normal mode.
 
+** Transclusion support
+To install [[https://github.com/nobiot/org-transclusion][org-transclusion]], which allows you to include a view of another file
+via a file link or an ID lin, set the =org-enable-transclusion-support= to =t=:
+
+#+BEGIN_SRC emacs-lisp
+  (setq-default dotspacemacs-configuration-layers
+   '((org :variables org-enable-transclusion-support t)))
+#+END_SRC
+
 ** Verb support
 To install [[https://github.com/federicotdn/verb][Verb]], an HTTP client based on Org mode, set the
 =org-enable-verb-support= variable to =t=:
@@ -1157,3 +1169,15 @@ Key binding prefixes:
 |-------------+-------------------------|
 | ~o~         | Follow link             |
 | ~r~         | Refresh org-roam buffer |
+
+** Transclusion
+| Key binding | Description                    |
+|-------------+--------------------------------|
+| ~SPC m u u~ | Transclude under cursor        |
+| ~SPC m u U~ | Transclude all in buffer       |
+| ~SPC m u d~ | De-transclude under cursor     |
+| ~SPC m u D~ | De-transclude all in buffer    |
+| ~SPC m u l~ | Demote transcluded subtree     |
+| ~SPC m u h~ | Promote transcluded subtree    |
+| ~SPC m u r~ | Refresh transclusion in buffer |
+| ~SPC m u g~ | Go to transclusion source      |

layers/+emacs/org/config.el

@@ -122,3 +122,6 @@ intelligence to attempt to determine the destination state.")
 
 (defvar org-enable-org-brain-support nil
   "If non-nil, enable org-brain")
+
+(defvar org-enable-transclusion-support nil
+  "If non-nil the `org-transclusion' package is configured.")

layers/+emacs/org/packages.el

@@ -71,6 +71,7 @@
     (org-roam :toggle org-enable-roam-support)
     (valign :toggle org-enable-valign)
     (org-appear :toggle org-enable-appear-support)
+    (org-transclusion :toggle org-enable-transclusion-support)
     (ox-asciidoc :toggle org-enable-asciidoc-support)))
 
 (defun org/post-init-company ()
@@ -1023,12 +1024,12 @@ Headline^^            Visit entry^^               Filter^^                    Da
     :config
     (spacemacs|diminish valign-mode " ㊣" " E")))
 
-(defun org/init-org-appear()
+(defun org/init-org-appear ()
   (use-package org-appear
     :defer t
     :init
     (progn
-      (add-hook 'org-mode-hook 'org-appear-mode)      
+      (add-hook 'org-mode-hook 'org-appear-mode)
       (setq org-appear-autolinks t
             org-appear-autoemphasis t
             org-appear-autosubmarkers t))
@@ -1040,6 +1041,22 @@ Headline^^            Visit entry^^               Filter^^                    Da
                   (add-hook 'evil-insert-state-entry-hook #'org-appear-manual-start nil t)
                   (add-hook 'evil-insert-state-exit-hook #'org-appear-manual-stop nil t))))))
 
+(defun org/init-org-transclusion ()
+  (use-package org-transclusion
+    :defer t
+    :init
+    (prog
+     (spacemacs/declare-prefix-for-mode 'org-mode "mu" "org-transclusion")
+     (spacemacs/set-leader-keys-for-major-mode 'org-mode
+       "uu" #'org-transclusion-add
+       "uU" #'org-transclusion-add-all
+       "ud" #'org-transclusion-remove
+       "uD" #'org-transclusion-remove-all
+       "ul" #'org-transclusion-demote-subtree
+       "uh" #'org-transclusion-promote-subtree
+       "ur" #'org-transclusion-refresh
+       "ug" #'org-transclusion-move-to-source))))
+
 (defun org/init-ox-asciidoc ()
   (use-package ox-asciidoc
     :after ox))