add example that shows how to access page number from converter in an inline macro

2 files changed, 30 insertions, 0 deletions

diff --git a/docs/modules/extend/examples/inline-pagenum-macro.rb b/docs/modules/extend/examples/inline-pagenum-macro.rb
new file mode 100644
index 00000000..1fbc9961
--- /dev/null
+++ b/docs/modules/extend/examples/inline-pagenum-macro.rb
@@ -0,0 +1,8 @@
+Asciidoctor::Extensions.register do
+  inline_macro :pagenum do
+    format :short
+    process do |parent|
+      create_inline parent, :quoted, parent.document.converter.page_number.to_s
+    end
+  end
+end
diff --git a/docs/modules/extend/pages/use-cases.adoc b/docs/modules/extend/pages/use-cases.adoc
index d7e69ad5..b45bce61 100644
--- a/docs/modules/extend/pages/use-cases.adoc
+++ b/docs/modules/extend/pages/use-cases.adoc
@@ -216,6 +216,28 @@ image:
   float-gap: [12, 6]
 ----
 
+== Access page number from inline macro
+
+Although not an extended converter, this use case uses information from the converter in much the same way.
+In this case, we're interested in retrieving the page number and inserting it into the content.
+
+Let's create an inline macro named `pagenum` that inserts the current page number into the document when the macro is converted.
+
+[,ruby]
+----
+include::example$inline-pagenum-macro.rb[]
+----
+
+Here's how this macro would be used.
+
+[,asciidoc]
+----
+= Document Title
+:doctype: book
+
+You're looking at page number pagenum:[].
+----
+
 == Resources
 
 To find even more examples of how to override the behavior of the converter, refer to the extended converter in the {url-infoq-template}[InfoQ Mini-Book template^].