asciidoctor-anywhere-footnote 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 460bfe36b3fb2aa22460bc048a5c75bd381e29e6497a20fed19961aa87f95078
+  data.tar.gz: 523ef6f8922a038e95d8f1ff41ce71a9046b04521efd51ff87ee87ecdf8d8504
+SHA512:
+  metadata.gz: 154194eeae784ea2b8522e6d5590afc9e22aaf277be7adbd82936e52f4a17d8b5ce135096e75e69b0aaa829df6d04aab5520f05bc393454d94d3f654337cb558
+  data.tar.gz: dd9cab18382358f98eb2fb25889d25d5e0178e11b4c088e3f8ad154d57f8797dd6e962dd4a8909b8effec8433e82fd8767c4a49715695667a88a29f6aafffe70

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Ray Offiah>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,209 @@
+# Asciidoctor Anywhere Footnote
+
+## Introduction
+
+We've all been there: you're out in the pouring rain with a flat battery.
+What's worse, when you pop the boot, you realize that you've left the spare charging in the garage.
+And to top it all, you still have that AsciiDoc table that's going to need a lot of footnotes.
+
+That's going to be a real bind if you want them to show up near the table, instead of right at the end of the page.
+
+Well, there's little you can do about the rain and the flat battery, but there may be something you can do about the footnotes. …
+
+## Anywhere Footnote
+
+This is an inline macro that you can use in most places that you'd be able to use `footnote`.
+The main difference is that it includes a parameter that it uses to reference the location of the footnote block:
+
+```asciidoc
+This is a piece of text{empty}afnote:footnote-block[This is the text of the footnote.]
+```
+
+
+The macro parameter (`footnote-block`) points to the `afnote` block where the footnote will be rendered:
+
+```asciidoc
+This is where the footnote block goes:
+
+afnote::footnote-block[]
+```
+> **Note**: Block macros must appear on their own line with no other characters.
+
+
+> **Tip** You can also use a single colon for the footnote block macro. (`afnote:footnote-block[]`)
+
+All the footnotes with the same identifier will be rendered in the same block,
+so you can have multiple footnote blocks on your page.
+
+The inline tag (single colon) supports extra parameters, as well as the text for the footnote.
+
+```
+afnote:my-block[Footnote text] // (1)
+afnote:my-block[reftext="Footnote text", refid="footnote-id"] // (2)
+afnote:my-block[refid="footnote-id"] (3)
+afnote:my-block[reftext="Footnote text", marker="*"] (4)
+afnote:my-block[reftext="Footnote text", lbrace="(" rbrace=")"] (5)
+```
+
+
+1. The standard pattern. The text in brackets will be used as the footnote.
+2. You can also set the footnote text using the `reftext` parameter. In this case we’re also using the `refid` to set a reusable reference identifier.
+3. The `refid` is used to reference an existing footnote so that multiple footnote references can point to the same footnote.
+4. Normally, the footnotes are numbered per block, but if you wish, you can assign your own marker for any footnote.
+5. As a default, the footnote markers are encased in square brackets. You can change this (to parentheses, for example)
+   by using the `lbrace` and/or `rbrace` parameters.
+
+> **Tip** If you don't want any kind of bracket encasing the footnote,
+> then set both `lbrace` and `rbrace` to `{empty} or empty strings.`
+>
+> You don't have to use both parameters. If you set `lbrace={empyty}` and  `rbrace=")"`, for example, you can footnote marked like this: `1)`
+
+## The Stylesheet
+
+The footnotes and the footnote block are rendered in HTML with an attached style (`anywhere-footnote`).
+It's included here for reference:
+
+```css
+.afnote-marker {
+   vertical-align: super;
+   font-size: 100%;
+   text-decoration: none;
+}
+
+.afnote-marker::before {
+   content: "[";
+}
+
+.afnote-marker::after {
+   content: "]";
+}
+
+.afnote-block {
+   text-decoration: none;
+}
+
+.afnote-hr-divider {
+   height: 1px;
+   background-color: #ccc; /* Standard gray color similar to default HR */
+   border: none;
+   margin: 0.5em 0; /* Standard HR margin */
+   width: 20%;
+}
+
+div.afnote-horizontal dl {
+   display: grid;
+   grid-template-columns: 30px auto;
+   grid-column-gap: 1px;
+}
+
+/* Force each dt and dd to be on the same line */
+div.afnote-horizontal dl > dt,
+div.afnote-horizontal dl > dd {
+   display: inline !important;
+   vertical-align: top !important;
+   margin: 0 !important;
+   padding: 0 !important;
+}
+
+/* Remove margins from paragraphs inside dd */
+div.afnote-horizontal dl > dd p {
+   display: inline;
+   margin: 0;
+   padding: 0;
+}
+
+```
+
+## Omitting the separator
+
+Normally, the footnote block is rendered with a short horizontal line above the footnotes:
+
+![footnote separator](footnote-separator.png "Footnote separator")
+
+To omit the separator, add the `omit-separator` attribute to the block tag.
+
+```asciidoc
+afnote:footnote-block[omit-separator="true"]
+```
+![Footnotes without separator](footnote-without-separator.png "Footnotes without separators")
+
+## Alternative counting formats
+
+By default, the footnotes will be counted using the standard Arabic notion (1, 2, 3, …).
+But other forms can be used by adding an attribute selector to your page:
+
+```asciidoc
+:afnote-format: alpha
+```
+The footnotes will use a single letter as a footnote marker.
+
+
+> ** Warning** Do not use this format if you have more than 26 footnotes on your page.
+
+You can also use roman numerals.
+
+```asciidoc
+:afnote-format: roman
+```
+
+> ** Warning** Do not use this format if you have more than 3999 footnotes on your page.
+> (Though if you did then I suspect footnote formatting would be the least of your problems)
+
+Omit the `afnote-format` attribute for standard arabic, or use:
+
+```asciidoc
+:afnote-format: arabic
+```
+
+> ** Note ** Bear in mind that the roman format will take up more space 
+## Controlling the Count
+
+Normally, the footnotes are numbered page-wide: starting at 1 then continuing to the end of the page.
+If you prefer the count reset to be reset to 1 each time a new block is encountered,
+then put this near the top of the page (before the first footnote):
+
+```asciidoc
+:afnote-block-reset: true
+```
+
+## Suppressing the separators globally
+
+There is also the option of suppressing the separators for the entire page  
+by declaring the following variable near the top of the page (before the first footnote):
+
+```asciidoc
+:afnote-omit-separators: true
+```
+
+## Running the Extension
+
+Add the extension to your Node installation:
+
+```shell
+npm i asciidoctor-anywhere-footnote
+```
+Then extension can be used with an AsciiDoctor ``convert()`` call:
+
+```javascript
+
+registry = asciidoctor.Extensions.create();
+require('../anywhere-footnote-processor')(registry);
+
+let converted_doc = asciidoctor.convert(input_document,{safe: 'safe', standalone: true,
+   extension_registry: registry})
+```
+
+Or as part of your Antora installation:
+ 
+```yaml
+  extensions:
+  - asciidoctor-kroki
+  - asciidoctor-external-callout
+  - '@asciidoctor/tabs'
+  - asciidoctor-anywhere-footnote
+```
+
+
+
+
+

data/asciidoctor-anywhere-footnote.gemspec

@@ -0,0 +1,34 @@
+# asciidoctor-anywhere-footnote.gemspec
+Gem::Specification.new do |spec|
+  spec.name          = "asciidoctor-anywhere-footnote"
+  spec.version       = "1.0.0"
+  spec.authors       = ["Ray Offiah"]
+  spec.email         = ["ray.offiah@couchbase.com"]
+
+  spec.summary       = "An Asciidoctor extension for placing footnotes anywhere in the document"
+  spec.description   = "This extension allows you to place footnotes near their referenced content rather than at the end of the document, with support for multiple footnote blocks, custom formatting, and reference management."
+  spec.homepage      = "https://github.com/yourusername/asciidoctor-anywhere-footnote"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.5.0"
+
+  # Specify which files should be added to the gem when it is released
+  spec.files         = Dir[
+    "lib/**/*",
+    "README.md",
+    "LICENSE",
+    "*.gemspec"
+  ]
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_runtime_dependency "asciidoctor", "~> 2.0"
+  spec.add_runtime_dependency "ruby-enum", "~> 1.0"
+  spec.add_runtime_dependency "roman-numerals", "~> 0.3"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/asciidoctor/anywhere_footnote_processor.rb

@@ -0,0 +1,245 @@
+require 'asciidoctor'
+require 'ruby-enum'
+require 'roman-numerals'
+
+
+
+Asciidoctor::Extensions.register do
+
+  $footnote_list = []
+
+  inline_macro AnywhereFootnoteProcessor
+
+end
+
+class Format
+  include Ruby::Enum
+
+  define :ARABIC, 'arabic'
+  define :ROMAN, 'roman'
+  define :ALPHA, 'alpha'
+
+end
+
+
+class AnywhereFootnote
+  attr_accessor :block_id, :ref_id, :text_parameter, :footnote_marker, :lbrace, :rbrace
+
+  def initialize
+
+    @block_id = ""
+    @ref_id = ""
+    @text_parameter = ""
+    @footnote_marker = ""
+    @lbrace = ""
+    @rbrace = ""
+  end
+end
+
+class AnywhereFootnoteProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+
+  use_dsl
+
+  named :afnote
+
+  AFNOTE_FORMAT = 'afnote-format'
+  AFNOTE_BLOCK_RESET = 'afnote-block-reset'
+  AFNOTE_OMIT_SEPARATORS ="afnote-omit-separators"
+  OMIT_SEPARATOR = 'omit-separator'
+
+  AFNOTE_ID_PREFIX = 'afnote-id-prefix'
+  AFNOTE_CSS_PREFIX = 'afnote-css-prefix'
+
+  AFNOTE_ID_DEFAULT_PREFIX = 'afnote-'
+  AFNOTE_CSS_DEFAULT_PREFIX = 'afnote-'
+
+  $afnote_id_prefix = AFNOTE_ID_DEFAULT_PREFIX
+  $afnote_css_prefix = AFNOTE_CSS_DEFAULT_PREFIX
+
+  def initialize(backend, document)
+    super
+    @name = 'afnote'
+    @document = document
+
+  end
+
+
+  def process(parent, target, attrs)
+
+    document = parent.document
+
+    afnote_format = Format.key(document.attr(AFNOTE_FORMAT) || 'arabic')
+
+    omit_separators_page_wide = document.attr? AFNOTE_OMIT_SEPARATORS, "true"
+
+    $afnote_id_prefix = document.attr(AFNOTE_ID_PREFIX) || AFNOTE_ID_DEFAULT_PREFIX
+    $afnote_css_prefix = document.attr(AFNOTE_CSS_PREFIX) || AFNOTE_CSS_DEFAULT_PREFIX
+
+    footnote = AnywhereFootnote.new
+
+    if target[0] == ':' or   attrs.empty? or attrs.has_key? OMIT_SEPARATOR
+
+      omit_separator = attrs[OMIT_SEPARATOR] == 'true'
+
+      block_id = target[0] == ':' ? target[1..-1] : target
+      return process_footnote_block(parent, block_id, (omit_separator or omit_separators_page_wide))
+
+
+    end
+
+    block_reset = document.attr? AFNOTE_BLOCK_RESET, "true"
+
+
+    footnote.block_id = target
+
+    # This means we have at least a single text parameter
+    footnote.text_parameter = attrs[1] || attrs['reftext'] || ""
+
+    footnote.ref_id = attrs['refid'] || (number_of_footnotes_in_block(footnote.block_id, false) + 1).to_s
+
+    footnote.footnote_marker = attrs['marker'] if attrs.has_key? 'marker'
+
+    footnote.lbrace = attrs['lbrace'] || ''
+    footnote.rbrace = attrs['rbrace'] || ''
+    
+    add_footnote_reference(footnote, block_reset, afnote_format)
+
+    #  This odd bit of code is to ensure that we don't end up setting duplicate anchor ids
+    #  for footnotes that reference other footnotes. In this case, the second footnote
+    #  is assigned another random string, which means we won't be able to click to it
+    # from the footnote block.
+
+    id_string = if $footnote_list.any? { |f| f.ref_id == footnote.ref_id }
+                  ""
+                else
+                  "#{$afnote_id_prefix}#{footnote.block_id}-#{footnote.ref_id}"
+                end
+
+    inline = create_footnote_reference(footnote, id_string)
+
+    $footnote_list << footnote
+
+    self.create_inline parent, :quoted, inline, :attributes => { 'role' => "#{$afnote_css_prefix}marker" }
+
+  end
+
+  def add_footnote_reference(footnote, block_reset = false, format = :ARABIC)
+
+    # First, find the highest footnote number.
+    # The easiest thing to do is
+    #  count the number of footnotes in each block
+    counter = number_of_footnotes_in_block(footnote.block_id, block_reset) + 1
+
+    if footnote.ref_id and  footnote.text_parameter.empty?
+
+      referenced_footnote = get_existing_footnote_marker($footnote_list, footnote.ref_id)
+      # Add nil checking.
+      footnote.footnote_marker = referenced_footnote&.footnote_marker
+      footnote.ref_id = referenced_footnote&.ref_id
+
+    else
+      if footnote.footnote_marker.empty?
+        footnote.footnote_marker = formatted_number(counter, format)
+      end
+    end
+
+  end
+
+  def get_existing_footnote_marker(footnote_list, ref_id)
+
+    footnote_list.find { |f| f.ref_id == ref_id and not f.text_parameter.empty?}
+
+  end
+
+  def process_footnote_block(parent, target, omit_separator)
+
+    block_id = target
+
+    grouped_footnotes = $footnote_list.group_by { |f| f.block_id }
+    selected_block = grouped_footnotes[block_id]
+
+    unless selected_block
+      throw "No footnotes found for block #{block_id}"
+    end
+
+    # Add an ID marker
+    footnote_block_id_text  = "[[#{$afnote_id_prefix}#{block_id}]]\n"
+
+
+    separator_text = if omit_separator
+                       ""
+                     else
+                       self.create_block(parent, :paragraph, "", {"role" => "#{$afnote_css_prefix}hr-divider"}).convert
+                     end
+
+    footnote_block_list = self.create_list(parent, :dlist, {"role" => "#{$afnote_css_prefix}horizontal"})
+
+    selected_block.each do |footnote|
+
+      unless footnote.text_parameter.empty?
+
+        # Some footnotes in the list are pointers to other footnotes.
+        # If you have duplicate markers, then you will not be able to
+        # point back to the original footnote. (Which one would you point back to?)
+        # Instead, just use a fake reference when the block is rendered.
+
+        xref_text = $footnote_list.count { |f| f.ref_id == footnote.ref_id } <= 1 ? "xref:#{$afnote_id_prefix}#{footnote.block_id}-#{footnote.ref_id}-ref" : "xref:#"
+
+        term = "[[#{$afnote_id_prefix}#{footnote.block_id}-#{footnote.ref_id}-def]]#{xref_text}[#{footnote.lbrace}#{footnote.footnote_marker}#{footnote.rbrace}, role=\"#{$afnote_css_prefix}marker\"]"
+
+        description = "#{footnote.text_parameter}"
+
+        dlist_term = self.create_list_item(footnote_block_list, term)
+        dlist_description = self.create_list_item(footnote_block_list, description)
+
+        dlist_item = [[dlist_term], dlist_description]
+
+        footnote_block_list.items << dlist_item
+      end
+
+    end
+
+    self.create_inline parent, :quoted, "#{footnote_block_id_text}\n#{separator_text}\n#{footnote_block_list.convert}", :attributes => { 'role' => "#{$afnote_css_prefix}block" }
+
+
+  end
+
+  def create_footnote_reference(footnote, id_string)
+
+    base_xref = "xref:#{$afnote_id_prefix}#{footnote.block_id}-#{footnote.ref_id}-def[#{footnote.lbrace}#{footnote.footnote_marker}#{footnote.rbrace}]"
+
+    (not id_string.empty?) ? "[[#{id_string}-ref]]#{base_xref}" : base_xref
+
+  end
+
+  def number_of_footnotes_in_block(block_id, block_reset = false)
+
+    if block_reset
+      $footnote_list.find_all { |f| f.block_id == block_id and not f.text_parameter.empty? }.size
+    else
+      $footnote_list.find_all { |f| not f.text_parameter.empty? }.size
+    end
+
+  end
+
+  def formatted_number(number, format = :ARABIC)
+    case format
+    when :ARABIC
+      number.to_s
+    when :ROMAN
+      RomanNumerals.to_roman(number).downcase
+    when :ALPHA
+      number_to_letter(number)
+    else
+      throw "Unknown format"
+    end
+  end
+
+  def number_to_letter(num)
+    (num + 96).chr
+  end
+
+end
+
+
+

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-anywhere-footnote
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ray Offiah
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-enum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: roman-numerals
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: This extension allows you to place footnotes near their referenced content
+  rather than at the end of the document, with support for multiple footnote blocks,
+  custom formatting, and reference management.
+email:
+- ray.offiah@couchbase.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- asciidoctor-anywhere-footnote.gemspec
+- lib/asciidoctor/anywhere_footnote_processor.rb
+homepage: https://github.com/yourusername/asciidoctor-anywhere-footnote
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: An Asciidoctor extension for placing footnotes anywhere in the document
+test_files: []