equation-citator-webnote

Introduction

Web citation grammar support for Equation Citator exported citations. Including web citations support for equations, figures and custom callouts.

This package is designed for pages that already contain Equation Citator exported citation spans:

<span class="equation-citator-citation" data-ec-kind="eq" data-ec-refs="[...]">...</span>

This package provides two entry points:

• equation-citator/markdown-it: build-time target injection for Markdown-it.
• equation-citator/runtime: browser hover previews, stable target IDs, and navigation.

Compatibility

You can use obsidian-equation-citator plugin to generate the citation HTML label with correct format. For the obsidian equation-citator plugin, see https://github.com/FRIEDparrot/obsidian-equation-citator.

Minor-version compatibility is applied. That means, equation-citator-webnote (npm package) v1.3.xx is compatible with obsidian-equation-citator v1.3.x.

Markdown-it

import equationCitatorMarkdownIt from 'equation-citator/markdown-it'

md.use(equationCitatorMarkdownIt, {
  include: (env) => env.relativePath?.startsWith('knowledge-base/'),
  enableObsidianCallouts: true
})

This injects target metadata for math blocks with \tag{...}, figures, and Equation Citator callout blockquotes.

Markdown repo path and image resolution

For Obsidian-style image embeds such as ![[img.png]], the markdown-it plugin needs to know which Markdown repository root contains the file being parsed. Markdown-it itself does not provide a stable final webpage URL during build, so pathMapping is required.

pathMapping maps each web repo link to the matching Markdown repo path, the format is :

pathMapping: [
  { webRoot: markdownSourceRoot }
]

where markdownSourceRoot is the root you used to render the markdown file, for example, the markdown file is

md.use(equationCitatorMarkdownIt, {
  pathMapping: [
    { 'your-website.com/knowledge-base': 'docs/knowledge-base' }
  ]
})
/// in that case, you call : 
const contentHtml = markdownIt.render(markdown, env); 
/*
 * if env.markdwonPath is 'docs/knowledge-base/../img.png' with relative path to knowledge-base, it will be resolved as `/knowledge-base/../image.png`
 */

When parsing docs/knowledge-base/Equation-Citator-Tutorial/Quick Start.md, the plugin selects the first mapping whose Markdown repo path matches the file path. Then ![[Equation-Citator-Tutorial/assets/Equation Citator Logo.png]] resolves to /knowledge-base/Equation-Citator-Tutorial/assets/Equation%20Citator%20Logo.png.

The plugin reads the parsed file path from env.markdownPath. If your build tool exposes another source path shape, set env.markdownPath before the plugin rule runs:

md.core.ruler.before('inline', 'repo-markdown-path', (state) => {
  state.env.markdownPath = `docs/${state.env.relativePath}`
})

Multiple mappings are supported. The first entry whose Markdown repo path matches the file being parsed is used.

For exported cross-file citations, the markdown-it plugin enriches each ref that has file with a resolved local URL inside data-ec-refs. The runtime uses this local URL for cross-file preview and navigation; it does not recompute file paths in the browser.

Heading section links

By default, Equation Citator does not rewrite Obsidian section links because different site builders may use different heading ID algorithms.

md.use(equationCitatorMarkdownIt, {
  useHeadingIdSlug: false
})

With useHeadingIdSlug: false, section targets such as [[#Heading]], [[Page#Heading]], ![[#Heading]], and ![[Page#Heading]] are left as their original wiki-link text.

Set useHeadingIdSlug: true only when you want Equation Citator to own the heading IDs for rendered Markdown:

md.use(equationCitatorMarkdownIt, {
  useHeadingIdSlug: true,
  pathMapping: [
    { '/knowledge-base': 'docs/knowledge-base' }
  ]
})

When enabled, the plugin injects IDs into rendered heading tokens without modifying Markdown source files. Existing heading IDs are preserved. Missing IDs are generated from heading text with buildHeadingId(), with duplicate IDs receiving -2, -3, and so on.

For repeated headings, the first generated ID keeps the base slug and later generated IDs are numbered in render order, however, they will not be slugged :

## Same Heading
## Same Heading
## Same Heading

renders with heading IDs equivalent to:

<h2 id="same-heading">Same Heading</h2>
<h2 id="same-heading-2">Same Heading</h2>
<h2 id="same-heading-3">Same Heading</h2>

Section links are then rendered against those IDs:

• [[#Heading|label]] renders as a normal link to #heading.
• [[Page#Heading|label]] renders as a normal link to the resolved page URL plus #heading.
• ![[#Heading]] and ![[Page#Heading]] render as a jump link with text like Click here to jump to #Heading.

If another outline, sidebar, or heading plugin needs to use the same ID format, import the builder instead of copying the slug logic:

import { buildHeadingId } from 'equation-citator'

const id = buildHeadingId('My Heading')

Runtime

import { install } from 'equation-citator/runtime'

install({ router })

The runtime file should be copied into assets/runtime.js when building the docs because the generated docs pages need it in the browser.