Clarify in docs that source_location is not tracked by default (PR #4416)

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/modules/api/pages/sourcemap.adoc b/docs/modules/api/pages/sourcemap.adoc
index ed32891f..2bfb1b76 100644
--- a/docs/modules/api/pages/sourcemap.adoc
+++ b/docs/modules/api/pages/sourcemap.adoc
@@ -46,6 +46,26 @@ Here's an example of how to enable the sourcemap using the API:
 doc = Asciidoctor.load_file 'doc.adoc', safe: :safe, sourcemap: true
 ----
 
+Extensions can enable the sourcemap as such:
+
+[,ruby]
+----
+class Asciidoctor::Document
+  attr_writer :sourcemap unless method_defined? :sourcemap=
+end
+
+# A preprocessor that enables the sourcemap feature if not
+# already enabled via the API.
+Asciidoctor::Extensions.register do
+  preprocessor do
+    process do |doc, reader|
+      doc.sourcemap = true
+      nil
+    end
+  end
+end
+----
+
 Now that the sourcemap is enabled, you can access the source location of the block elements in the parsed document.
 
 == Use the sourcemap