#+options: num:nil toc:nil author:nil html-postamble:nil

* org-transclusion-http

Transclude content over HTTP in Org mode with [[https://nobiot.github.io/org-transclusion/][org-transclusion]]!

** Dependencies

~org-transclusion-http~ uses [[https://pandoc.org/][Pandoc]] to render HTML content as Org mode,
so to make full use of this package please ensure that the ~pandoc~
command is installed and in your ~PATH~.

** Installation

Install ~org-transclusion-http~ with ~M-x package-install RET
org-transclusion-http~ and then add the following snippet to your
configuration:

#+begin_src emacs-lisp
  (with-eval-after-load 'org-transclusion
    (add-to-list 'org-transclusion-extensions 'org-transclusion-http)
    (require 'org-transclusion-http))
#+end_src

** Usage

Add an ~org-transclusion~ link to an Org mode buffer:

#+begin_example
#+transclude: [[https://ushin.org/software.html]]
#+end_example

Then move point onto the link, and run ~M-x org-transclusion-add~.  Emacs
will download the webpage and convert its HTML content to Org mode
with Pandoc before displaying as an Org subtree in the same buffer.

~org-transclusion-http~ also handles non-HTML content, which will be
rendered as-is.

For more information on ~org-transclusion~, please see the [[https://nobiot.github.io/org-transclusion/][~org-transclusion~ manual]].

*** Transclude only content at HTML link fragment

When the ~#+transclude:~ link contains a link fragment, also known as an
anchor or target, ~org-transclusion-http~ attempts to guess which HTML
element(s) to transclude:

#+begin_example
#+transclude: [[https://ushin.org/needs-list.html#care]] # Just "Care" subtree
#+transclude: [[https://ushin.org/needs-list.html]]      # Whole file
#+end_example

To improve ~org-transclusion~'s ability to determine which HTML elements
to transclude based on the element its link fragment points to, please
patch the ~org-transclusion-html.el~ file in ~org-transclusion~ itself.

For more usage examples, please see the tests.

** Limitations

Certain features of ~org-transclusion~, such as live-syncing and opening
source buffers, are not supported.

~:lines~ are not yet supported.  Patches welcome!

** Bugs and Patches

Bugs can be submitted to the [[https://todo.sr.ht/~ushin/ushin][ushin issue tracker]].  Patches, comments or
questions can be submitted to the [[https://lists.sr.ht/~ushin/ushin][ushin public inbox]].

** Acknowledgments

- [[https://github.com/alphapapa/][Adam Porter]] for code review and bug fixes.
- [[https://amodernist.com/][Philip Kaludercic]] for code review.

** Changelog

*** 0.5-pre

Nothing yet...

*** 0.4

**** Fix

  - Fix byte compilation error.  Thanks to Chris Rayner for reporting!

*** 0.3

**** Internal

- Prepare for NonGNU ELPA submission.

*** 0.2

**** Change

- Better error message when ~pandoc~ is not available.

**** Fix

- Don't prompt to stop HTTP transclusion process when killing Emacs.

**** Internal

- Better recognition of Org and HTML documents.
- Update to match upstream ~org-transclusion~ API.
- More tests.

*** 0.1

Initial release.
