branch: externals/org-transclusion
commit f30a8dc0bd29ef312ea98a2142f3f8b6944a4756
Author: Joseph Turner <jos...@breatheoutbreathe.in>
Commit: Joseph Turner <jos...@breatheoutbreathe.in>
docs: Document org-transclusion-html
---
docs/org-transclusion-manual.org | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/docs/org-transclusion-manual.org b/docs/org-transclusion-manual.org
index 104ec325b0..bca7e04635 100644
--- a/docs/org-transclusion-manual.org
+++ b/docs/org-transclusion-manual.org
@@ -540,6 +540,24 @@ Example 5:
#+transclude: [[./things-at-point-dir/baz.el::id:1234567890][barz-baz-fuzz]]
:src elisp :thingatpt defun
#+end_example
+*** Transclude HTML content with Pandoc
+#+cindex: Transclude HTML content with Pandoc
+
+If you have Pandoc installed, you can transclude local HTML files
+as Org documents.
+
+This feature is provided as an [[#extensions][extension]] (default off).
+
+#+begin_example
+#+transclude: [[file:../test/source-html-no-ext]]
+#+end_example
+
+Since it's not currently possible to add anchor links to local =file:=
+Org links, HTML transclusions always render the entire document as
+Org. However, packages which transclude HTML documents over a
+network, such as [[https://git.sr.ht/~ushin/hyperdrive.el][hyperdrive.el]] and
[[https://git.sr.ht/~breatheoutbreathein/org-transclusion-http][org-transclusion-http]],
are able to
+render specific HTML elements by tag.
+
** Extensions
:PROPERTIES:
:CUSTOM_ID: extensions
@@ -550,6 +568,7 @@ Example 5:
#+cindex: Extension - org-transclusion-indent-mode
#+cindex: Extension - org-transclusion-src-lines
#+cindex: Extension - org-transclusion-font-lock
+#+cindex: Extension - org-transclusion-html
Org-transclusion provides a simple extension framework, where you can use
~customize~ to selectively add new features.
@@ -577,6 +596,9 @@ Currently, the following extensions are available.
- (on by default) ~org-transclusion-font-lock~ ::
Add font-lock for =#+transclude=. Org mode's standard syntax treats the
combination of a =#+transclude:= keyword and a link used by Org-transclusion as
a keyword. This means it applies the ~org-meta-line~ face and the link part
cannot be toggled as a normal link. This extension adds
~org-transclusion-keyword~ face to the keyword part and lets the link part to
be treated as a normal link for ~org-toggle-link-display~.
+- (off by default) ~org-transclusion-html~ ::
+ Transclude local HTML files by converting them to Org with Pandoc.
+
* Customizing
#+vindex: org-transclusion-extensions
