@peaceroad/markdown-it-footnote-here 0.2.1 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,33 @@
+# Workflow for Updating markdown-it-footnote-here
+
+This document captures the current implementation workflow, especially around footnotes/endnotes.
+
+## Code overview
+- `index.js`:
+  - Rendering helpers: `render_footnote_ref`, `render_footnote_open/close`, `render_footnote_anchor`, and `createAfterBackLinkToken`.
+  - Parsing: custom block rule `footnote_def`, inline rule `footnote_ref`, core rule `footnote_anchor`, and `endnotes_move` to append endnotes at the end.
+  - Endnote handling: labels starting with `endnotesPrefix` (default `en-`) are endnotes; DOM ids/classes use fixed `en`.
+  - Options include backlink placement, label customization, and endnotes section attributes.
+
+## Adding features / making changes
+1) Review options and defaults in `index.js` (`opt` object).
+2) Keep DOM prefixes stable:
+   - Footnotes use `fn`; endnotes use `en` for ids/classes (`en1`, `en-ref1`, etc.).
+3) Parsing flow:
+   - `footnote_def` registers notes into `env.footnotes` or `env.endnotes` based on `endnotesPrefix`.
+   - `footnote_ref` resolves references via `selectNoteEnv` and tags tokens with `isEndnote`.
+4) Rendering flow:
+   - `footnote_anchor` injects backlinks/labels into footnote content.
+   - `endnotes_move` removes endnote blocks from inline positions and appends a `<section>` (attributes ordered aria-label → id → class → role).
+5) When adding options:
+   - Update `README.md` and add fixtures under `test/`.
+   - Extend `test/test.js` to load the new fixtures.
+
+## Testing
+- Run `npm test` (uses `test/test.js` and fixtures under `test/`).
+- Fixtures format: alternating `[Markdown]` and `[HTML]` blocks.
+
+## Notes
+- `labelSupTag` applies to both footnotes and endnotes.
+- If `endnotesPrefix` is empty, endnotes are disabled.
+- `endnotesUseHeading` true: render `<h2>` with `endnotesSectionAriaLabel`; false: use `aria-label` without heading.

package/README.md

@@ -28,6 +28,34 @@ HTML:
 
 Notice. When multiple instances of the same footnote number appear in the main content, the default behavior is that the backlink from the footnote will refer to the first instance.
 
+## Endnotes
+
+When a footnote label starts with the endnote prefix (default: `en-`), it is collected at the end of the document and rendered as endnotes. The reference/backlink label for endnotes is prefixed by `endnotesLabelPrefix` (default: `E`), so endnotes appear as `[E1]`, `[E2]`, ...
+
+Markdown:
+
+```md
+A paragraph.[^en-1]
+
+[^en-1]: A endnote.
+
+A paragraph.
+```
+
+HTML:
+
+```html
+<p>A paragraph.<a href="#en1" id="en-ref1" class="en-noteref" role="doc-noteref">[E1]</a></p>
+<p>A paragraph.</p>
+<section aria-label="Notes" id="endnotes" role="doc-endnotes">
+<ol>
+<li id="en1">
+<p><a href="#en-ref1" class="en-backlink" role="doc-backlink">[E1]</a> A endnote.</p>
+</li>
+</ol>
+</section>
+```
+
 ## Use
 
 ```js
@@ -53,7 +81,13 @@ npm install @peaceroad/markdown-it-footnote-here
 - afterBacklinkSuffixArabicNumerals (boolean): If true, backlink suffix uses numbers (1, 2, ...) instead of letters (a, b, ...).
 - afterBacklinkdAriaLabelPrefix (string): Prefix for aria-label of backlink (default: 'Back to reference ').
 - labelBra (string): Bracket to use before footnote number (default: '[').
-- labelKet (string): Bracket to use after footnote number (default: ']').
+- labelKet (string): Bracket to use after footnote number (default: ']'). 
 - labelSupTag (boolean): If true, wraps footnote reference in `<sup>` tag.
 - backLabelBra (string): Bracket to use before backlink number (default: '[').
 - backLabelKet (string): Bracket to use after backlink number (default: ']').
+- endnotesPrefix (string): Prefix that marks a footnote as an endnote (default: `'en-'`).
+- endnotesLabelPrefix (string): Label prefix for endnote refs/backlinks (default: `'E'`, e.g., `[E1]`).
+- endnotesSectionId (string): `id` attribute for the endnotes section wrapper; omitted when empty (default: `'endnotes'`).
+- endnotesSectionClass (string): `class` attribute for the endnotes section wrapper; omitted when empty (default: `''`).
+- endnotesSectionAriaLabel (string): Used as `aria-label` when `endnotesUseHeading` is false. When `endnotesUseHeading` is true, this value becomes the heading text (default: `'Notes'`).
+- endnotesUseHeading (boolean): If true, render `<h2>{endnotesSectionAriaLabel}</h2>` and omit `aria-label`. If false (default), omit the heading and set `aria-label` when provided.

package/index.js

@@ -8,71 +8,124 @@ const render_footnote_anchor_name = (tokens, idx, opt, env) => {
   return prefix + n
 }
 
+const isEndnoteLabel = (label, opt) => {
+  if (!opt.endnotesPrefix) return false
+  return label.startsWith(opt.endnotesPrefix)
+}
+
+const ensureNotesEnv = (env, key) => {
+  if (!env[key]) {
+    env[key] = { length: 0, refs: {}, positions: [] }
+  }
+  return env[key]
+}
+
+const ENDNOTE_DOM_PREFIX = 'en'
+
+const getDomPrefix = (isEndnote) => (isEndnote ? ENDNOTE_DOM_PREFIX : 'fn')
+const getDisplayPrefix = (isEndnote, opt) => (isEndnote ? opt.endnotesLabelPrefix : '')
+
+const getNotesMeta = (token, env) => {
+  if (token.meta && token.meta.isEndnote) return env.endnotes
+  return env.footnotes
+}
+
+const selectNoteEnv = (label, env, preferEndnote) => {
+  const endRefs = env.endnotes && env.endnotes.refs
+  const footRefs = env.footnotes && env.footnotes.refs
+  const endId = endRefs && endRefs[':' + label]
+  const footId = footRefs && footRefs[':' + label]
+
+  if (preferEndnote && endId !== undefined) {
+    return { env: env.endnotes, id: endId, isEndnote: true }
+  }
+  if (footId !== undefined) {
+    return { env: env.footnotes, id: footId, isEndnote: false }
+  }
+  if (endId !== undefined) {
+    return { env: env.endnotes, id: endId, isEndnote: true }
+  }
+  return null
+}
+
 const render_footnote_ref = (tokens, idx, opt, env) => {
   const token = tokens[idx]
   const id = token.meta.id
   const n = id + 1
-  const footnotes = env.footnotes
-  footnotes._refCount = footnotes._refCount || {}
-  let refIdx = (footnotes._refCount[id] = (footnotes._refCount[id] || 0) + 1)
+  const notes = getNotesMeta(token, env)
+  const isEndnote = !!token.meta.isEndnote
+  const noteDomPrefix = getDomPrefix(isEndnote)
+  const displayPrefix = getDisplayPrefix(isEndnote, opt)
+  notes._refCount = notes._refCount || {}
+  let refIdx = (notes._refCount[id] = (notes._refCount[id] || 0) + 1)
   if (!opt.afterBacklinkSuffixArabicNumerals) {
     refIdx = String.fromCharCode(96 + refIdx)
   }
   let suffix = ''
-  let label = `${opt.labelBra}${n}${opt.labelKet}`
-  if (footnotes.totalCounts && footnotes.totalCounts[id] > 1) {
+  let label = `${opt.labelBra}${displayPrefix}${n}${opt.labelKet}`
+  if (notes.totalCounts && notes.totalCounts[id] > 1) {
     suffix = '-' + refIdx
     if (opt.beforeSameBacklink) {
-      label = `${opt.labelBra}${n}${suffix}${opt.labelKet}`
+      label = `${opt.labelBra}${displayPrefix}${n}${suffix}${opt.labelKet}`
     }
   }
-  let refCont = `<a href="#fn${n}" id="fn-ref${n}${suffix}" class="fn-noteref" role="doc-noteref">${label}</a>`
-  if (opt.labelSupTag) refCont = `<sup class="fn-noteref-wrapper">${refCont}</sup>`
+  const href = `${noteDomPrefix}${n}`
+  let refCont = `<a href="#${href}" id="${noteDomPrefix}-ref${n}${suffix}" class="${noteDomPrefix}-noteref" role="doc-noteref">${label}</a>`
+  if (opt.labelSupTag) refCont = `<sup class="${noteDomPrefix}-noteref-wrapper">${refCont}</sup>`
   return refCont
 }
 
 const render_footnote_open = (tokens, idx, opt, env, slf) => {
   const id = slf.rules.footnote_anchor_name(tokens, idx, opt, env, slf)
+  const isEndnote = tokens[idx].meta && tokens[idx].meta.isEndnote
+  if (isEndnote) return `<li id="${ENDNOTE_DOM_PREFIX}${id}">\n`
   return `<aside id="fn${id}" class="fn" role="doc-footnote">\n`
 }
 
-const render_footnote_close = () => {
+const render_footnote_close = (tokens, idx) => {
+  const isEndnote = tokens[idx].meta && tokens[idx].meta.isEndnote
+  if (isEndnote) return `</li>\n`
   return `</aside>\n`
 }
 
 const render_footnote_anchor = (tokens, idx, opt, env) => {
   const idNum = tokens[idx].meta.id
   const n = idNum + 1
-  const footnotes = env.footnotes
-  const counts = footnotes && footnotes.totalCounts
+  const isEndnote = tokens[idx].meta && tokens[idx].meta.isEndnote
+  const notes = getNotesMeta(tokens[idx], env)
+  const counts = notes && notes.totalCounts
+  const noteDomPrefix = getDomPrefix(!!isEndnote)
+  const displayPrefix = getDisplayPrefix(!!isEndnote, opt)
+
   if (opt.beforeSameBacklink && counts && counts[idNum] > 1) {
     let links = ''
     for (let i = 1; i <= counts[idNum]; i++) {
       const suffix = '-' + String.fromCharCode(96 + i); // a, b, c ...
-      links += `<a href="#fn-ref${n}${suffix}" class="fn-backlink" role="doc-backlink">${opt.backLabelBra}${n}${suffix}${opt.backLabelKet}</a>`
+      links += `<a href="#${noteDomPrefix}-ref${n}${suffix}" class="${noteDomPrefix}-backlink" role="doc-backlink">${opt.backLabelBra}${displayPrefix}${n}${suffix}${opt.backLabelKet}</a>`
     }
     return links + ' '
   }
 
   if (opt.afterBacklink) {
-    return `<span class="fn-label">${opt.backLabelBra}${n}${opt.backLabelKet}</span> `
+    return `<span class="${noteDomPrefix}-label">${opt.backLabelBra}${displayPrefix}${n}${opt.backLabelKet}</span> `
   }
 
   if (counts && counts[idNum] > 1) {
-    return `<a href="#fn-ref${n}-a" class="fn-backlink" role="doc-backlink">${opt.backLabelBra}${n}${opt.backLabelKet}</a> `
+    return `<a href="#${noteDomPrefix}-ref${n}-a" class="${noteDomPrefix}-backlink" role="doc-backlink">${opt.backLabelBra}${displayPrefix}${n}${opt.backLabelKet}</a> `
   }
 
-  return `<a href="#fn-ref${n}" class="fn-backlink" role="doc-backlink">${opt.backLabelBra}${n}${opt.backLabelKet}</a> `
+  return `<a href="#${noteDomPrefix}-ref${n}" class="${noteDomPrefix}-backlink" role="doc-backlink">${opt.backLabelBra}${displayPrefix}${n}${opt.backLabelKet}</a> `
 }
 
-function createAfterBackLinkToken(state, counts, n, opt) {
+function createAfterBackLinkToken(state, counts, n, opt, noteDomPrefix, isEndnote) {
+  const displayPrefix = isEndnote ? opt.endnotesLabelPrefix : ''
   let html = ' '
   if (counts && counts > 1) {
     for (let i = 1; i <= counts; i++) {
       const suffixChar = opt.afterBacklinkSuffixArabicNumerals ? i : String.fromCharCode(96 + i)
       const suffix = '-' + suffixChar
-      html += `<a href="#fn-ref${n}${suffix}" class="fn-backlink" role="doc-backlink"`
-      if (opt.afterBacklinkdAriaLabelPrefix) html += ` aria-label="${opt.afterBacklinkdAriaLabelPrefix}${n}${suffix}"`
+      html += `<a href="#${noteDomPrefix}-ref${n}${suffix}" class="${noteDomPrefix}-backlink" role="doc-backlink"`
+      if (opt.afterBacklinkdAriaLabelPrefix) html += ` aria-label="${opt.afterBacklinkdAriaLabelPrefix}${displayPrefix}${n}${suffix}"`
       html += `>${opt.afterBacklinkContent}`
       if (opt.afterBacklinkWithNumber) {
         html += `<sup>${suffixChar}</sup>`
@@ -80,8 +133,8 @@ function createAfterBackLinkToken(state, counts, n, opt) {
       html += `</a>`
     }
   } else {
-    html += `<a href="#fn-ref${n}" class="fn-backlink" role="doc-backlink"`
-    if (opt.afterBacklinkdAriaLabelPrefix) html += ` aria-label="${opt.afterBacklinkdAriaLabelPrefix}${n}"`
+    html += `<a href="#${noteDomPrefix}-ref${n}" class="${noteDomPrefix}-backlink" role="doc-backlink"`
+    if (opt.afterBacklinkdAriaLabelPrefix) html += ` aria-label="${opt.afterBacklinkdAriaLabelPrefix}${displayPrefix}${n}"`
     html += `>${opt.afterBacklinkContent}</a>`
   }
   const token = new state.Token('html_inline', '', 0)
@@ -102,16 +155,22 @@ const footnote_plugin = (md, option) =>{
     afterBacklinkWithNumber: false,
     afterBacklinkSuffixArabicNumerals: false,
     afterBacklinkdAriaLabelPrefix: 'Back to reference ', /* 戻る：本文参照 */
+    endnotesPrefix: 'en-',
+    endnotesLabelPrefix: 'E',
+    endnotesSectionId: 'endnotes',
+    endnotesSectionClass: '',
+    endnotesSectionAriaLabel: 'Notes',
+    endnotesUseHeading: false,
   }
   if (option) Object.assign(opt, option)
 
   const isSpace = md.utils.isSpace
 
   md.renderer.rules.footnote_ref = (tokens, idx, _options, env) => render_footnote_ref(tokens, idx, opt, env)
-  md.renderer.rules.footnote_open = render_footnote_open
-  md.renderer.rules.footnote_close = render_footnote_close
+  md.renderer.rules.footnote_open = (tokens, idx, _options, env, slf) => render_footnote_open(tokens, idx, opt, env, slf)
+  md.renderer.rules.footnote_close = (tokens, idx, _options, env, slf) => render_footnote_close(tokens, idx, opt, env, slf)
   md.renderer.rules.footnote_anchor = (tokens, idx, _options, env, slf) => render_footnote_anchor(tokens, idx, opt, env, slf)
-  md.renderer.rules.footnote_anchor_name  = render_footnote_anchor_name
+  md.renderer.rules.footnote_anchor_name  = (tokens, idx, _options, env, slf) => render_footnote_anchor_name(tokens, idx, opt, env, slf)
 
   // Process footnote block definition
   const footnote_def = (state, startLine, endLine, silent) => {
@@ -134,16 +193,13 @@ const footnote_plugin = (md, option) =>{
 
     if (silent) { return true; }
 
-    // initialize footnotes environment once
-    if (!state.env.footnotes) {
-      state.env.footnotes = { length: 0, refs: {}, positions: [] }
-    }
-    const fn = state.env.footnotes
+    const isEndnote = isEndnoteLabel(label, opt)
+    const fn = ensureNotesEnv(state.env, isEndnote ? 'endnotes' : 'footnotes')
     const id = fn.length++
     fn.refs[':' + label] = id
 
     const token = new state.Token('footnote_open', '', 1)
-    token.meta = { id, label }
+    token.meta = { id, label, isEndnote }
     token.level = state.level++
     state.tokens.push(token)
     fn.positions.push(state.tokens.length - 1)
@@ -193,6 +249,7 @@ const footnote_plugin = (md, option) =>{
 
     const closeToken = new state.Token('footnote_close', '', -1)
     closeToken.level = --state.level
+    closeToken.meta = { isEndnote }
     state.tokens.push(closeToken)
 
     return true
@@ -208,9 +265,6 @@ const footnote_plugin = (md, option) =>{
       return false
     }
 
-    const env = state.env
-    if (!env.footnotes || !env.footnotes.refs) { return false; }
-
     let pos = start + 2
     let found = false
     for (; pos < posMax && !found; pos++) {
@@ -223,12 +277,13 @@ const footnote_plugin = (md, option) =>{
     pos++; // pos set next ']' position.
 
     const label = src.slice(start + 2, pos - 1)
-    const id = env.footnotes.refs[':' + label]
-
-    if (id === undefined) { return false; }
+    const env = state.env
+    const preferEndnote = isEndnoteLabel(label, opt)
+    const resolved = selectNoteEnv(label, env, preferEndnote)
 
+    if (!resolved) { return false; }
     if (!silent) {
-      const fn = env.footnotes
+      const fn = resolved.env
 
       if (!fn.list) { fn.list = []; }
 
@@ -236,10 +291,10 @@ const footnote_plugin = (md, option) =>{
       fn.list[footnoteId] = { label, count: 0 }
 
       fn.totalCounts = fn.totalCounts || {}
-      fn.totalCounts[id] = (fn.totalCounts[id] || 0) + 1
+      fn.totalCounts[resolved.id] = (fn.totalCounts[resolved.id] || 0) + 1
 
       const token = state.push('footnote_ref', '', 0)
-      token.meta = { id, label }
+      token.meta = { id: resolved.id, label, isEndnote: resolved.isEndnote }
     }
 
     state.pos = pos
@@ -247,42 +302,103 @@ const footnote_plugin = (md, option) =>{
   }
 
   const footnote_anchor = (state) => {
+    if (!state.env.footnotes && !state.env.endnotes) return
     const tokens = state.tokens
-    const fn = state.env.footnotes
-    const positions = fn && fn.positions
-    if (!positions || positions.length === 0) { return; }
-
-    const createAnchorToken = (id) => {
+    const createAnchorToken = (id, isEndnote) => {
       const aToken = new state.Token('footnote_anchor', '', 0)
-      aToken.meta = { id, label: id + 1 }
+      aToken.meta = { id, label: id + 1, isEndnote }
       return aToken
     }
 
-    for (let j = 0, len = positions.length; j < len; ++j) {
-      const posOpen = positions[j]
-      if (posOpen + 2 >= tokens.length) continue
+    const injectAnchors = (notes, isEndnote) => {
+      const positions = notes && notes.positions
+      if (!positions || positions.length === 0) { return; }
+
+      for (let j = 0, len = positions.length; j < len; ++j) {
+        const posOpen = positions[j]
+        if (posOpen + 2 >= tokens.length) continue
 
-      const t1 = tokens[posOpen + 1]
-      if (t1.type !== 'paragraph_open') continue
+        const t1 = tokens[posOpen + 1]
+        if (t1.type !== 'paragraph_open') continue
 
-      const t2 = tokens[posOpen + 2]
-      if (t2.type !== 'inline') continue
+        const t2 = tokens[posOpen + 2]
+        if (t2.type !== 'inline') continue
 
-      const t0 = tokens[posOpen]
-      const id = t0.meta.id
+        const t0 = tokens[posOpen]
+        const id = t0.meta.id
+        const noteDomPrefix = isEndnote ? ENDNOTE_DOM_PREFIX : 'fn'
 
-      t2.children.unshift(createAnchorToken(id))
-      if (opt.afterBacklink) {
-        const n = id + 1
-        const counts = fn.totalCounts && fn.totalCounts[id]
-        t2.children.push(createAfterBackLinkToken(state, counts, n, opt))
+        t2.children.unshift(createAnchorToken(id, isEndnote))
+        if (opt.afterBacklink) {
+          const n = id + 1
+          const counts = notes.totalCounts && notes.totalCounts[id]
+          t2.children.push(createAfterBackLinkToken(state, counts, n, opt, noteDomPrefix, isEndnote))
+        }
       }
     }
+
+    injectAnchors(state.env.footnotes, false)
+    injectAnchors(state.env.endnotes, true)
+  }
+
+  const move_endnotes_to_section = (state) => {
+    if (!opt.endnotesPrefix) return
+    if (!state.env.endnotes || !state.env.endnotes.positions || state.env.endnotes.positions.length === 0) {
+      return
+    }
+
+    const tokens = state.tokens
+    const endnoteBlocks = []
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i]
+      if (token.type !== 'footnote_open' || !token.meta || !token.meta.isEndnote) continue
+
+      let j = i + 1
+      while (j < tokens.length) {
+        const t = tokens[j]
+        if (t.type === 'footnote_close' && t.meta && t.meta.isEndnote) {
+          j++
+          break
+        }
+        j++
+      }
+      endnoteBlocks.push(tokens.slice(i, j))
+      tokens.splice(i, j - i)
+      i--
+    }
+
+    if (endnoteBlocks.length === 0) return
+
+    const sectionOpen = new state.Token('html_block', '', 0)
+    const attrs = []
+    if (!opt.endnotesUseHeading && opt.endnotesSectionAriaLabel) {
+      attrs.push(`aria-label="${opt.endnotesSectionAriaLabel}"`)
+    }
+    if (opt.endnotesSectionId) attrs.push(`id="${opt.endnotesSectionId}"`)
+    if (opt.endnotesSectionClass) attrs.push(`class="${opt.endnotesSectionClass}"`)
+    attrs.push('role="doc-endnotes"')
+    let sectionContent = `<section ${attrs.join(' ')}>\n`
+    if (opt.endnotesUseHeading && opt.endnotesSectionAriaLabel) {
+      sectionContent += `<h2>${opt.endnotesSectionAriaLabel}</h2>\n`
+    }
+    sectionContent += '<ol>\n'
+    sectionOpen.content = sectionContent
+
+    const sectionClose = new state.Token('html_block', '', 0)
+    sectionClose.content = '</ol>\n</section>\n'
+
+    tokens.push(sectionOpen)
+    endnoteBlocks.forEach(block => {
+      tokens.push(...block)
+    })
+    tokens.push(sectionClose)
   }
 
   md.block.ruler.before('reference', 'footnote_def', footnote_def, { alt: [ 'paragraph', 'reference' ] })
   md.inline.ruler.after('image', 'footnote_ref', footnote_ref)
   md.core.ruler.after('inline', 'footnote_anchor', footnote_anchor)
+  md.core.ruler.after('footnote_anchor', 'endnotes_move', move_endnotes_to_section)
 }
 
 export default footnote_plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peaceroad/markdown-it-footnote-here",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A markdown-it plugin. This generate aside[role|doc-footnote] element just below the footnote reference paragraph.",
   "main": "index.js",
   "type":"module",