@peaceroad/markdown-it-renderer-fence 0.6.0 → 0.7.0

package/README.md

@@ -115,11 +115,12 @@ Note:
 
 - `samp` rendering for `samp`, `shell`, `console` languages.
 - line number wrapping via `start` (`line-number-start` long form) / `data-pre-start`.
-- line number skip/reset controls via `line-number-skip` / `line-number-reset`.
+- line number skip/set controls via `line-number-skip` / `line-number-set`.
 - emphasized lines via `em-lines` / `emphasize-lines`.
 - optional line-end spacer via `lineEndSpanThreshold`.
 - optional pre-wrap support via `wrap` / `pre-wrap`.
 - comment line markers via `comment-mark`.
+- sidecar line notes via immediate `line-notes` fence (`notes` alias).
 
 ### Fence Attribute Examples
 
@@ -157,7 +158,7 @@ console.log(a)
 Advanced line number control:
 
 ~~~md
-```txt {start="25" line-number-skip="5" line-number-reset="6:136"}
+```txt {start="25" line-number-skip="5" line-number-set="6:136"}
 line1
 line2
 line3
@@ -168,7 +169,7 @@ line6
 ~~~
 
 ```html
-<pre><code class="language-txt" data-pre-start="25" data-pre-line-number-skip="5" data-pre-line-number-reset="6:136" style="counter-set:pre-line-number 25;">
+<pre><code class="language-txt" data-pre-start="25" data-pre-line-number-skip="5" data-pre-line-number-set="6:136" style="counter-set:pre-line-number 25;">
 <span class="pre-line">line1</span>
 <span class="pre-line">line2</span>
 <span class="pre-line">line3</span>
@@ -229,38 +230,76 @@ echo 1
 </samp></pre>
 ```
 
+Line notes:
+
+~~~md
+```js {start="5"}
+const a = 1
+console.log(a)
+```
+```line-notes
+1: setup {width="7em"}
+2：result {width="10em"}
+```
+~~~
+
+```html
+<div class="pre-wrapper-line-notes" data-pre-line-notes-layout="anchor"><pre><code class="language-js" data-pre-start="5" data-pre-line-notes="true" style="counter-set:pre-line-number 5;"><span class="pre-line pre-line-has-end-note" data-pre-line-note-from="1" data-pre-line-note-to="1"><span class="pre-line-content" style="anchor-name:--pre-line-note-1;" aria-describedby="pre-line-note-1-1-1">const a = 1</span></span>
+<span class="pre-line pre-line-has-end-note" data-pre-line-note-from="2" data-pre-line-note-to="2"><span class="pre-line-content" style="anchor-name:--pre-line-note-2;" aria-describedby="pre-line-note-1-1-2">console.log(a)</span></span>
+</code></pre><div class="pre-line-note-layer"><div id="pre-line-note-1-1-1" class="pre-line-note" role="note" data-pre-line-note-from="1" data-pre-line-note-to="1" data-pre-line-note-label="1" style="position-anchor:--pre-line-note-1; --line-note-width:7em;">setup</div><div id="pre-line-note-1-1-2" class="pre-line-note" role="note" data-pre-line-note-from="2" data-pre-line-note-to="2" data-pre-line-note-label="2" style="position-anchor:--pre-line-note-2; --line-note-width:10em;">result</div></div></div>
+```
+
 ### Markup Notes
 
 - `useHighlightPre: true` keeps highlighter-provided `<pre><code>` when present.
 - In that passthrough path, line-splitting features are intentionally disabled:
   - line numbers
   - `line-number-skip`
-  - `line-number-reset`
+  - `line-number-set`
   - `em-lines`
   - line-end spacer
   - `comment-mark`
+  - `line-notes`
   - `samp` conversion
 
-Official line-number CSS contract:
+Reference line-number CSS contract:
 
-```css
-.pre-line {
-  counter-increment: pre-line-number;
-}
+Minimum counter contract:
 
-.pre-line::before {
+```css
+pre :is(code, samp)[data-pre-start] .pre-line::before {
   content: counter(pre-line-number);
 }
 
-.pre-line.pre-line-no-number {
-  counter-increment: none;
+pre :is(code, samp)[data-pre-start] .pre-line::after {
+  content: "";
+  counter-increment: pre-line-number;
 }
 
-.pre-line.pre-line-no-number::before {
+pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::before {
   content: "";
 }
+
+pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::after {
+  counter-increment: none;
+}
 ```
 
+Recommended display CSS:
+
+- See [`example/line-number.css`](./example/line-number.css) for the full reference stylesheet.
+- See [`example/line-number-sample.html`](./example/line-number-sample.html) for Markdown / Preview / HTML side-by-side examples.
+- See [`example/line-notes.css`](./example/line-notes.css) for the companion line-note stylesheet.
+- See [`example/line-notes-sample.html`](./example/line-notes-sample.html) for sidecar line-note examples.
+
+Note:
+
+- renderer-fence emits `counter-set` as the displayed line number value itself
+- the reference CSS increments the counter in `span.pre-line::after`, so `start="1"` maps directly to `counter-set:pre-line-number 1;`
+- `line-number-set="6:136"` similarly emits `counter-set:pre-line-number 136;` on that line wrapper
+- the minimum contract above is the required part; `example/line-number.css` adds gutter width, divider line, and whitespace handling
+- if a consumer uses a different counter strategy, its CSS must be aligned with this HTML contract
+
 ### Markup Options
 
 - `attrsOrder` (default: `['class', 'id', 'data-*', 'style']`): output attribute order (`data-*` wildcard supported).
@@ -287,13 +326,34 @@ Line-number attr syntax note:
 
 - `line-number-start` is the long form of `start`; rendered output still uses `data-pre-start`.
 - `line-number-skip` supports single values (`2`), ranges (`4-6`), and open-ended forms (`3-`).
-- `line-number-reset` uses `line:number` pairs (for example `6:136,14:220`).
-- `line-number-skip` / `line-number-reset` are applied only when source and highlighted logical line counts match; otherwise renderer falls back to plain sequential numbering.
+- `line-number-set` uses `line:number` pairs (for example `6:136,14:220`).
+- `line-number-skip` and `line-number-set` must not target the same source line. If they overlap, the skipped line stays blank and the conflicting `line-number-set` entry is ignored.
+- `line-number-skip` / `line-number-set` are applied only when source and highlighted logical line counts match; otherwise renderer falls back to plain sequential numbering.
+
+Line-note syntax note:
+
+- `line-notes` is the canonical sidecar fence name; `notes` is a short alias.
+- Sidecar notes are folded only when they immediately follow a code/samp fence.
+- Immediate sidecar folding is fail-closed: if any non-empty line is malformed, a note entry is incomplete, or the same note start line appears twice, the `line-notes` fence stays as a normal literal fence block.
+- Syntax supports `N: text`, `N-M: text`, `N：text`, and `N-M：text`.
+- Per-note attrs can be appended in markdown-it-attrs style on the same line for single-line notes, for example `5: cache lookup key {width="8rem"}`.
+- For multiline notes, prefer a trailing attrs-only continuation line, for example `  {width="11rem"}`.
+- Continuation lines start with indentation (`  ` or tab) and append multiline note text to the previous note.
+- Output keeps note text outside `<code>/<samp>` in a sibling note layer for safer copy semantics.
+- Line-note blocks use the external wrapper contract `pre-wrapper-line-notes`.
+- `data-pre-line-notes-layout="anchor"` is added only for simple non-overlapping note layouts. The current check is intentionally lightweight: it uses the note start line plus the note text's explicit logical line count, so a two-line note starting at line `3` prevents another anchored note from starting at line `4`.
+- This anchor-safety check does not measure CSS wrapping. If a note wraps because of narrow CSS width, consumer CSS should still be prepared to fall back to a below-block list.
+- When anchor positioning is unavailable or the layout is not marked safe, consumer CSS should render notes as a below-block list. The reference stylesheet uses `data-pre-line-note-label` so the fallback still shows which source line each note belongs to.
+- In anchor layouts, the rendered line HTML carries note metadata on `.pre-line`, and the anchor itself is attached to `.pre-line-content` so notes can start from the rendered code end.
+- Accessibility contract: the rendered `.pre-line-content` carries `aria-describedby`, and each note item renders with a stable `id` plus `role="note"`, so assistive tech can associate the note text with its anchor line.
+- When a sidecar fence is folded, the previous fence token `map` is extended to cover the absorbed note-fence lines so editor scroll/jump integrations can still treat the merged output as one source span.
+- `line-notes` are applied only when source and highlighted logical line counts match; otherwise note markup is skipped.
 
 Migration note (`0.5.0`):
 
 - `comment-line` / `data-pre-comment-line` / `pre-comment-line` were removed
 - use `comment-mark` / `data-pre-comment-mark` / `pre-line-comment`
+- `line-number-reset` was removed; use `line-number-set`
 
 ## Custom Highlight API Mode (Experimental / Advanced)
 
@@ -519,6 +579,7 @@ Then include that bridge in generated HTML:
 - `customHighlight.idPrefix` (default: `'hl-'`): generated per-block payload id prefix.
 - `customHighlight.scopePrefix` (default: `'hl'`): scope name prefix used for highlight registration.
 - `customHighlight.lineFeatureStrategy` (`'hybrid' | 'disable'`, default: `'hybrid'`): keep or disable line-span features in API rendering.
+- In `NODE_ENV=development`, invalid known enum-like values and unknown `customHighlight` keys emit warn-once diagnostics while keeping normalized fallback behavior.
 
 ### API Helper Exports
 
@@ -532,11 +593,19 @@ Then include that bridge in generated HTML:
 - `customHighlightPayloadSchemaVersion`
 - `customHighlightPayloadSupportedVersions`
 
+### Runtime Version Policy
+
+- `applyCustomHighlights(..., { strictVersion: true })` accepts only `customHighlightPayloadSupportedVersions` (currently `v:1`).
+- `supportedVersion` / `supportedVersions` allow explicit accepted payload versions.
+- If `strictVersion` is `true`, it takes precedence and custom accepted versions are ignored.
+
 ## Docs and Examples
 
 - API styling guide: `docs/custom-highlight-styling-guide.md`
 - default preset CSS sample: `docs/default-highlight-theme.css`
 - provider matrix page: `example/custom-highlight-provider-matrix.html`
+- line-number sample: `example/line-number-sample.html`
+- line-notes sample: `example/line-notes-sample.html`
 
 ## Tests and Benchmarks
 
@@ -547,8 +616,6 @@ Then include that bridge in generated HTML:
 - performance baseline: `npm run test:performance`
 - runtime apply benchmark: `npm run test:performance:runtime`
 
-## License and Notices
+## License
 
 - Project license: MIT (`LICENSE`)
-- Third-party notices: `THIRD_PARTY_NOTICES.md`
-- `docs/default-highlight-theme.css` contains mappings derived from highlight.js theme families (BSD-3-Clause; see notices).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peaceroad/markdown-it-renderer-fence",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "In code blocks, the `<samp>` tag is used with the language keywords `samp`, `shell`, and `console`, and provides an option to display line numbers.",
   "main": "index.js",
   "exports": {
@@ -13,7 +13,6 @@
     "index.js",
     "src",
     "LICENSE",
-    "THIRD_PARTY_NOTICES.md",
     "README.md"
   ],
   "type": "module",
@@ -42,10 +41,10 @@
   "repository": "https://github.com/peaceroad/p7d-markdown-it-renderer-fence",
   "license": "MIT",
   "devDependencies": {
-    "@peaceroad/markdown-it-figure-with-p-caption": "^0.16.0",
+    "@peaceroad/markdown-it-figure-with-p-caption": "^0.17.0",
     "highlight.js": "^11.11.1",
-    "markdown-it": "^14.1.0",
+    "markdown-it": "^14.1.1",
     "markdown-it-attrs": "^4.3.1",
-    "shiki": "^3.21.0"
+    "shiki": "^4.0.2"
   }
 }

package/src/custom-highlight/option-validator.js

@@ -42,6 +42,15 @@ const knownCustomHighlightKeys = new Set([
   'theme',
 ])
 
+const isExactValidOptionValue = (value, validSet) => {
+  return typeof value === 'string' && validSet.has(value)
+}
+
+const isNormalizedValidOptionValue = (value, validSet) => {
+  if (typeof value !== 'string') return false
+  return validSet.has(value.trim().toLowerCase())
+}
+
 const validateCustomHighlightOptions = (rawOpt, normalizedOpt) => {
   if (!rawOpt || typeof rawOpt !== 'object') return
 
@@ -54,31 +63,31 @@ const validateCustomHighlightOptions = (rawOpt, normalizedOpt) => {
     }
   }
 
-  if (rawOpt.provider != null && !validProviderSet.has(normalizedOpt.provider)) {
+  if (rawOpt.provider != null && !isExactValidOptionValue(rawOpt.provider, validProviderSet)) {
     warnOptionIssueOnce(
       'provider',
       `Invalid customHighlight.provider "${String(rawOpt.provider)}". Using "${normalizedOpt.provider}".`,
     )
   }
-  if (rawOpt.fallback != null && !validFallbackSet.has(normalizedOpt.fallback)) {
+  if (rawOpt.fallback != null && !isExactValidOptionValue(rawOpt.fallback, validFallbackSet)) {
     warnOptionIssueOnce(
       'fallback',
       `Invalid customHighlight.fallback "${String(rawOpt.fallback)}". Using "${normalizedOpt.fallback}".`,
     )
   }
-  if (rawOpt.transport != null && !validTransportSet.has(normalizedOpt.transport)) {
+  if (rawOpt.transport != null && !isExactValidOptionValue(rawOpt.transport, validTransportSet)) {
     warnOptionIssueOnce(
       'transport',
       `Invalid customHighlight.transport "${String(rawOpt.transport)}". Using "${normalizedOpt.transport}".`,
     )
   }
-  if (rawOpt.lineFeatureStrategy != null && !validLineFeatureStrategySet.has(normalizedOpt.lineFeatureStrategy)) {
+  if (rawOpt.lineFeatureStrategy != null && !isExactValidOptionValue(rawOpt.lineFeatureStrategy, validLineFeatureStrategySet)) {
     warnOptionIssueOnce(
       'line-feature-strategy',
       `Invalid customHighlight.lineFeatureStrategy "${String(rawOpt.lineFeatureStrategy)}". Using "${normalizedOpt.lineFeatureStrategy}".`,
     )
   }
-  if (rawOpt.shikiScopeMode != null && !validShikiScopeModeSet.has(normalizedOpt.shikiScopeMode)) {
+  if (rawOpt.shikiScopeMode != null && !isNormalizedValidOptionValue(rawOpt.shikiScopeMode, validShikiScopeModeSet)) {
     warnOptionIssueOnce(
       'shiki-scope-mode',
       `Invalid customHighlight.shikiScopeMode "${String(rawOpt.shikiScopeMode)}". Using "${normalizedOpt.shikiScopeMode}".`,

package/src/custom-highlight/scope-name.js

@@ -0,0 +1,23 @@
+const highlightNameUnsafeReg = /[^A-Za-z0-9_-]+/g
+const hyphenMultiReg = /-+/g
+
+const sanitizeHighlightNamePart = (value, fallback = '') => {
+  let safe = String(value == null ? '' : value)
+    .replace(highlightNameUnsafeReg, '-')
+    .replace(hyphenMultiReg, '-')
+    .replace(/^-+|-+$/g, '')
+  if (!safe) safe = fallback
+  if (/^[0-9]/.test(safe)) safe = 'x-' + safe
+  if (safe.startsWith('--')) safe = safe.slice(2) || fallback
+  return safe
+}
+
+const sanitizeHighlightName = (name, prefix = '') => {
+  const safe = sanitizeHighlightNamePart(name, 'scope')
+  const prefixBase = sanitizeHighlightNamePart(prefix, '')
+  return prefixBase ? `${prefixBase}-${safe}` : safe
+}
+
+export {
+  sanitizeHighlightName,
+}

package/src/entry/markup-highlight.js

@@ -4,6 +4,9 @@ import {
   finalizeCommonFenceOption,
   prepareFenceRenderContext,
 } from '../fence/render-shared.js'
+import {
+  installLineNotesCoreRule,
+} from '../fence/line-notes.js'
 import {
   renderFenceMarkup,
 } from '../fence/render-markup.js'
@@ -17,6 +20,7 @@ const mditRendererFenceMarkup = (md, option) => {
   }
 
   finalizeCommonFenceOption(opt)
+  installLineNotesCoreRule(md)
 
   md.renderer.rules.fence = (tokens, idx, options, env, slf) => {
     const context = prepareFenceRenderContext(tokens, idx, opt)

package/src/fence/line-notes.js

@@ -0,0 +1,181 @@
+import {
+  getInfoAttr,
+} from '../utils/attr-utils.js'
+
+const lineNotesRuleName = 'renderer_fence_line_notes'
+const lineNotesMetaKey = '__rendererFenceLineNotes'
+const lineNotesInstalledKey = '__rendererFenceLineNotesInstalled'
+const fenceInfoNameReg = /^([^{\s]*)/
+const lineNoteHeaderReg = /^\s*([1-9]\d*)(?:\s*-\s*([1-9]\d*))?\s*[:：]\s*(.*)$/
+const lineNoteContinuationReg = /^(?: {2,}|\t)/
+const lineNoteFenceNameSet = new Set(['line-notes', 'notes'])
+const lineNoteAttrsReg = /^(.*?)(?:\s+\{([^{}]+)\})\s*$/
+const lineNoteAttrsOnlyReg = /^\{([^{}]+)\}\s*$/
+const lineNoteWidthReg = /^(?:\d+(?:\.\d+)?|\.\d+)(?:px|em|rem|ch|vw|svw|lvw|dvw|%)$/
+
+const getFenceInfoName = (info) => {
+  const match = String(info ?? '').trim().match(fenceInfoNameReg)
+  return match ? match[1] : ''
+}
+
+const stripContinuationIndent = (line) => {
+  if (!line) return ''
+  if (line[0] === '\t') return line.slice(1)
+  if (line.startsWith('  ')) return line.slice(2)
+  return line
+}
+
+const parseValidatedLineNoteWidth = (attrText) => {
+  if (!attrText || attrText.indexOf('width') === -1) return ''
+  const attrs = getInfoAttr(attrText)
+  if (!attrs.length) return ''
+  for (let i = 0; i < attrs.length; i++) {
+    const name = attrs[i][0]
+    const value = String(attrs[i][1] || '').trim()
+    if (name !== 'width') continue
+    if (lineNoteWidthReg.test(value)) return value
+  }
+  return ''
+}
+
+const parseLineNoteHeaderText = (text) => {
+  const str = String(text ?? '')
+  if (str.indexOf('{') === -1 || str.indexOf('}') === -1) {
+    return { text: str, width: '' }
+  }
+  const match = str.match(lineNoteAttrsReg)
+  if (!match) return { text: str, width: '' }
+  return {
+    text: match[1].trimEnd(),
+    width: parseValidatedLineNoteWidth(match[2]),
+  }
+}
+
+const parseLineNoteAttrsOnlyText = (text) => {
+  const str = String(text ?? '').trim()
+  if (str[0] !== '{' || str[str.length - 1] !== '}') return null
+  const match = str.match(lineNoteAttrsOnlyReg)
+  if (!match) return null
+  const width = parseValidatedLineNoteWidth(match[1])
+  return width ? { width } : null
+}
+
+const parseLineNotesContent = (content) => {
+  const raw = String(content ?? '')
+  if (!raw || (raw.indexOf(':') === -1 && raw.indexOf('：') === -1)) return []
+  const lines = raw.split('\n')
+  const notes = []
+  const seenStarts = new Set()
+  let current = null
+
+  const pushCurrent = () => {
+    if (!current) return true
+    if (!current.lines.length) return false
+    notes.push({
+      from: current.from,
+      to: current.to,
+      text: current.lines.join('\n'),
+      lineCount: current.lines.length,
+      width: current.width || '',
+    })
+    seenStarts.add(current.from)
+    current = null
+    return true
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const header = line.match(lineNoteHeaderReg)
+    if (header) {
+      if (!pushCurrent()) return null
+      let from = Number(header[1])
+      let to = header[2] ? Number(header[2]) : from
+      if (from > to) {
+        const swap = from
+        from = to
+        to = swap
+      }
+      if (seenStarts.has(from)) return null
+      current = {
+        from,
+        to,
+        lines: [],
+        width: '',
+      }
+      const parsed = parseLineNoteHeaderText(header[3])
+      current.width = parsed.width
+      if (parsed.text) current.lines.push(parsed.text)
+      continue
+    }
+
+    if (current && lineNoteContinuationReg.test(line)) {
+      const stripped = stripContinuationIndent(line)
+      const attrsOnly = parseLineNoteAttrsOnlyText(stripped)
+      if (attrsOnly) {
+        if (attrsOnly.width) current.width = attrsOnly.width
+        continue
+      }
+      current.lines.push(stripped)
+      continue
+    }
+
+    if (!line.trim()) {
+      continue
+    }
+
+    return null
+  }
+
+  if (!pushCurrent()) return null
+  return notes
+}
+
+const getTokenLineNotes = (token) => {
+  if (!token || !token.meta || typeof token.meta !== 'object') return null
+  const notes = token.meta[lineNotesMetaKey]
+  return Array.isArray(notes) && notes.length ? notes : null
+}
+
+const setTokenLineNotes = (token, notes) => {
+  if (!token || !notes || !notes.length) return
+  if (!token.meta || typeof token.meta !== 'object') token.meta = {}
+  token.meta[lineNotesMetaKey] = notes
+}
+
+const extendTokenMapWithImmediateFollower = (token, next) => {
+  if (!token || !Array.isArray(token.map) || token.map.length !== 2) return
+  if (!next || !Array.isArray(next.map) || next.map.length !== 2) return
+  const start = token.map[0]
+  const end = next.map[1]
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) return
+  if (end > token.map[1]) token.map = [start, end]
+}
+
+const installLineNotesCoreRule = (md) => {
+  if (!md || md[lineNotesInstalledKey]) return
+  md[lineNotesInstalledKey] = true
+  md.core.ruler.after('block', lineNotesRuleName, (state) => {
+    const tokens = state && state.tokens
+    if (!Array.isArray(tokens) || tokens.length < 2) return
+
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const token = tokens[i]
+      const next = tokens[i + 1]
+      if (!token || token.type !== 'fence' || !next || next.type !== 'fence') continue
+      const nextName = getFenceInfoName(next.info)
+      if (!lineNoteFenceNameSet.has(nextName)) continue
+      const currentName = getFenceInfoName(token.info)
+      if (lineNoteFenceNameSet.has(currentName)) continue
+      const notes = parseLineNotesContent(next.content)
+      if (!notes || !notes.length) continue
+      setTokenLineNotes(token, notes)
+      extendTokenMapWithImmediateFollower(token, next)
+      tokens.splice(i + 1, 1)
+    }
+  })
+}
+
+export {
+  getTokenLineNotes,
+  installLineNotesCoreRule,
+}

package/src/fence/render-api-provider.js

@@ -15,6 +15,9 @@ import {
 import {
   validateCustomHighlightOptions,
 } from '../custom-highlight/option-validator.js'
+import {
+  sanitizeHighlightName,
+} from '../custom-highlight/scope-name.js'
 import {
   commentLineClass,
   normalizeEmphasisRanges,
@@ -31,7 +34,6 @@ import {
 } from './render-api-constants.js'
 
 const highlightNameUnsafeReg = /[^A-Za-z0-9_-]+/g
-const hyphenMultiReg = /-+/g
 
 const defaultCustomHighlightOpt = {
   provider: 'shiki',
@@ -183,16 +185,6 @@ const shouldApplyApiFallbackForReason = (chOpt, reason) => {
   return chOpt._fallbackOnSet.has(reason)
 }
 
-const sanitizeHighlightName = (name, prefix = '') => {
-  const prefixBase = String(prefix == null ? '' : prefix).replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  const raw = String(name || '')
-  let safe = raw.replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  if (!safe) safe = 'scope'
-  if (/^[0-9]/.test(safe)) safe = 'x-' + safe
-  if (safe.startsWith('--')) safe = safe.slice(2) || 'scope'
-  return prefixBase ? `${prefixBase}-${safe}` : safe
-}
-
 const uniqueHighlightName = (base, usedMap) => {
   if (!usedMap.has(base)) {
     usedMap.set(base, 1)
@@ -805,6 +797,5 @@ export {
   normalizeCustomHighlightOpt,
   renderCustomHighlightPayloadScript,
   renderCustomHighlightScopeStyleTag,
-  sanitizeHighlightName,
   shouldApplyApiFallbackForReason,
 }

package/src/fence/render-api-renderer.js

@@ -11,7 +11,9 @@ import {
   orderTokenAttrs,
   preWrapStyle,
   resolveAdvancedLineNumberPlan,
+  resolveLineNotesPlan,
   splitFenceBlockToLines,
+  wrapFencePreWithLineNotes,
 } from './render-shared.js'
 import {
   createApiPayloadForFence,
@@ -26,6 +28,8 @@ import {
   renderFenceMarkup,
 } from './render-markup.js'
 
+const apiDisableLineFeatureList = Object.freeze(['setLineNumber', 'line-number-skip', 'line-number-set', 'lineEndSpanThreshold', 'line-notes'])
+
 let fallbackCustomHighlightSeq = 0
 
 const nextCustomHighlightId = (env, prefix) => {
@@ -45,23 +49,30 @@ const buildApiPreAttrs = (preWrapValue, wrapEnabled, opt) => {
   return preAttrs
 }
 
-const renderFenceApiOrPlain = (token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberResetValue, wrapEnabled, preWrapValue, commentMarkValue, includePayload, timings) => {
+const renderFenceApiOrPlain = (token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, includePayload, timings) => {
   const isSamp = opt._sampReg.test(lang)
   const tag = isSamp ? 'samp' : 'code'
   let content = md.utils.escapeHtml(token.content)
   const lineStrategy = opt.customHighlight.lineFeatureStrategy
   const needLineNumber = lineStrategy === 'hybrid' && opt.setLineNumber && startNumber >= 0
   const needEndSpan = lineStrategy === 'hybrid' && opt.lineEndSpanThreshold > 0
+  const needAdvancedLineNumberPlan = needLineNumber && (lineNumberSkipValue !== undefined || lineNumberSetValue !== undefined)
+  const needLineNotes = lineStrategy !== 'disable' && !!(lineNotes && lineNotes.length)
+  const logicalLineCount = (needAdvancedLineNumberPlan || needLineNotes)
+    ? getLogicalLineCount(token.content)
+    : -1
   let lineNumberPlan = null
-  if (needLineNumber && (lineNumberSkipValue !== undefined || lineNumberResetValue !== undefined)) {
-    const logicalLineCount = getLogicalLineCount(token.content)
-    lineNumberPlan = resolveAdvancedLineNumberPlan(lineNumberSkipValue, lineNumberResetValue, logicalLineCount, logicalLineCount)
+  if (needAdvancedLineNumberPlan) {
+    lineNumberPlan = resolveAdvancedLineNumberPlan(lineNumberSkipValue, lineNumberSetValue, logicalLineCount, logicalLineCount)
   }
-  if (needLineNumber || needEndSpan) {
+  const lineNotePlan = needLineNotes
+    ? resolveLineNotesPlan(lineNotes, logicalLineCount, logicalLineCount, lineNoteIdPrefix)
+    : null
+  if (needLineNumber || needEndSpan || lineNotePlan) {
     const splitStartedAt = timings ? getNowMs() : 0
     const nlIndex = content.indexOf('\n')
     const br = nlIndex > 0 && content[nlIndex - 1] === '\r' ? '\r\n' : '\n'
-    content = splitFenceBlockToLines(content, [], needLineNumber, false, needEndSpan, opt.lineEndSpanThreshold, opt.lineEndSpanClass, br, undefined, commentLineClass, lineNumberPlan)
+    content = splitFenceBlockToLines(content, [], needLineNumber, false, needEndSpan, opt.lineEndSpanThreshold, opt.lineEndSpanClass, br, undefined, commentLineClass, lineNumberPlan, lineNotePlan)
     if (timings) addTimingMs(timings, 'lineSplitMs', getNowMs() - splitStartedAt)
   }
 
@@ -88,7 +99,8 @@ const renderFenceApiOrPlain = (token, lang, md, opt, slf, env, startNumber, emph
 
   if (preAttrs.length) orderTokenAttrs({ attrs: preAttrs }, opt)
   const preAttrsText = preAttrs.length ? slf.renderAttrs({ attrs: preAttrs }) : ''
-  const html = `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>\n`
+  const preHtml = `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>`
+  const html = wrapFencePreWithLineNotes(preHtml, lineNotePlan)
   return inlinePayloadScript ? html + inlinePayloadScript : html
 }
 
@@ -101,10 +113,12 @@ const getFenceHtml = (context, md, opt, slf, env) => {
   const startNumber = context.startNumber
   const emphasizeLines = context.emphasizeLines
   const lineNumberSkipValue = context.lineNumberSkipValue
-  const lineNumberResetValue = context.lineNumberResetValue
+  const lineNumberSetValue = context.lineNumberSetValue
   const wrapEnabled = context.wrapEnabled
   const preWrapValue = context.preWrapValue
   const commentMarkValue = context.commentMarkValue
+  const lineNotes = context.lineNotes
+  const lineNoteIdPrefix = context.lineNoteIdPrefix
 
   const apiDecisionBase = {
     renderer: 'api',
@@ -112,11 +126,11 @@ const getFenceHtml = (context, md, opt, slf, env) => {
     fallbackUsed: false,
     lineFeatureStrategy: opt.customHighlight.lineFeatureStrategy,
     disabledFeatures: opt.customHighlight.lineFeatureStrategy === 'disable'
-      ? ['setLineNumber', 'line-number-skip', 'line-number-reset', 'lineEndSpanThreshold']
+      ? apiDisableLineFeatureList
       : [],
   }
   try {
-    const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberResetValue, wrapEnabled, preWrapValue, commentMarkValue, true, timings)
+    const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, true, timings)
     if (timingEnabled) apiDecisionBase.timings = finalizeFenceTimings(timings, fenceStartedAt)
     emitFenceDecision(opt, apiDecisionBase)
     return html
@@ -130,7 +144,7 @@ const getFenceHtml = (context, md, opt, slf, env) => {
         reason: 'provider-error',
         lineFeatureStrategy: opt.customHighlight.lineFeatureStrategy,
       }
-      const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberResetValue, wrapEnabled, preWrapValue, commentMarkValue, false, timings)
+      const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, false, timings)
       if (timingEnabled) fallbackDecision.timings = finalizeFenceTimings(timings, fenceStartedAt)
       emitFenceDecision(opt, fallbackDecision)
       return html

package/src/fence/render-api-runtime.js

@@ -4,6 +4,9 @@ import {
   getPayloadMapFromScript,
   styleToHighlightCss,
 } from '../custom-highlight/runtime-utils.js'
+import {
+  sanitizeHighlightName,
+} from '../custom-highlight/scope-name.js'
 import {
   customHighlightAppliedAttr,
   customHighlightAppliedSelector,
@@ -19,17 +22,6 @@ const globalRuntimeInsertedScopeStyles = new Map()
 const runtimeInsertedScopeStylesByDoc = new WeakMap()
 const runtimeApplyStateByRoot = new WeakMap()
 const validColorSchemeSet = new Set(['light', 'dark', 'auto'])
-const highlightNameUnsafeReg = /[^A-Za-z0-9_-]+/g
-const hyphenMultiReg = /-+/g
-
-const sanitizeHighlightName = (name) => {
-  const raw = String(name || '')
-  let safe = raw.replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  if (!safe) safe = 'scope'
-  if (/^[0-9]/.test(safe)) safe = 'x-' + safe
-  if (safe.startsWith('--')) safe = safe.slice(2) || 'scope'
-  return safe
-}
 
 const getCustomHighlightBlockId = (node) => {
   if (!node || typeof node.getAttribute !== 'function') return null
@@ -133,10 +125,10 @@ const addMediaQueryChangeListener = (queryList, listener) => {
 }
 
 const getRuntimeSupportedPayloadVersions = (options = {}) => {
-  const set = new Set()
   if (options.strictVersion === true) {
-    for (const v of customHighlightPayloadSupportedVersions) set.add(v)
+    return new Set(customHighlightPayloadSupportedVersions)
   }
+  const set = new Set()
   if (Number.isSafeInteger(options.supportedVersion)) set.add(options.supportedVersion)
   if (Array.isArray(options.supportedVersions)) {
     for (const v of options.supportedVersions) {

package/src/fence/render-api.js

@@ -7,6 +7,9 @@ import {
   finalizeCommonFenceOption,
   prepareFenceRenderContext,
 } from './render-shared.js'
+import {
+  installLineNotesCoreRule,
+} from './line-notes.js'
 import {
   customHighlightDataEnvKey,
   customHighlightEnvInitRuleName,
@@ -73,6 +76,7 @@ const mditRendererFenceCustomHighlight = (md, option) => {
   }
 
   finalizeCommonFenceOption(opt)
+  installLineNotesCoreRule(md)
 
   md.core.ruler.before('block', customHighlightEnvInitRuleName, (state) => {
     const env = state && state.env

package/src/fence/render-markup.js

@@ -14,12 +14,16 @@ import {
   orderTokenAttrs,
   preWrapStyle,
   resolveAdvancedLineNumberPlan,
+  resolveLineNotesPlan,
   splitFenceBlockToLines,
+  wrapFencePreWithLineNotes,
 } from './render-shared.js'
 import {
   parsePreCodeWrapper,
 } from '../utils/pre-code-wrapper-parser.js'
 
+const markupPassthroughDisabledFeatures = Object.freeze(['setLineNumber', 'line-number-skip', 'line-number-set', 'setEmphasizeLines', 'lineEndSpanThreshold', 'comment-mark', 'line-notes', 'samp'])
+
 const renderFenceMarkup = (context, md, opt, slf) => {
   const token = context.token
   const lang = context.lang
@@ -29,10 +33,12 @@ const renderFenceMarkup = (context, md, opt, slf) => {
   const startNumber = context.startNumber
   const emphasizeLines = context.emphasizeLines
   const lineNumberSkipValue = context.lineNumberSkipValue
-  const lineNumberResetValue = context.lineNumberResetValue
+  const lineNumberSetValue = context.lineNumberSetValue
   const wrapEnabled = context.wrapEnabled
   const preWrapValue = context.preWrapValue
   const commentMarkValue = context.commentMarkValue
+  const lineNotes = context.lineNotes
+  const lineNoteIdPrefix = context.lineNoteIdPrefix
 
   const isSamp = opt._sampReg.test(lang)
   const sourceContent = token.content
@@ -76,7 +82,7 @@ const renderFenceMarkup = (context, md, opt, slf) => {
       passthrough: true,
       passthroughReason: 'pre-code-parse-failed',
       hasHighlightPre: false,
-      disabledFeatures: ['setLineNumber', 'setEmphasizeLines', 'lineEndSpanThreshold', 'comment-mark', 'samp'],
+      disabledFeatures: markupPassthroughDisabledFeatures,
     }
     if (timingEnabled) decision.timings = finalizeFenceTimings(timings, fenceStartedAt)
     emitFenceDecision(opt, decision)
@@ -105,7 +111,8 @@ const renderFenceMarkup = (context, md, opt, slf) => {
   if (preAttrs.length) orderTokenAttrs({ attrs: preAttrs }, opt)
   const preAttrsText = preAttrs.length ? slf.renderAttrs({ attrs: preAttrs }) : ''
 
-  const needLineNumber = opt.setLineNumber && startNumber >= 0
+  const useHighlightPre = opt.useHighlightPre && hasHighlightPre
+  const needLineNumber = !useHighlightPre && opt.setLineNumber && startNumber >= 0
   let sourceLogicalLineCount = -1
   let highlightedLogicalLineCount = -1
   const ensureLogicalLineCounts = () => {
@@ -113,18 +120,22 @@ const renderFenceMarkup = (context, md, opt, slf) => {
     if (highlightedLogicalLineCount === -1) highlightedLogicalLineCount = getLogicalLineCount(content)
   }
   let normalizedEmphasis = []
-  if (opt.setEmphasizeLines && emphasizeLines.length > 0) {
+  if (!useHighlightPre && opt.setEmphasizeLines && emphasizeLines.length > 0) {
     ensureLogicalLineCounts()
     normalizedEmphasis = normalizeEmphasisRanges(emphasizeLines, highlightedLogicalLineCount)
   }
   let lineNumberPlan = null
-  if (needLineNumber && (lineNumberSkipValue !== undefined || lineNumberResetValue !== undefined)) {
+  if (needLineNumber && (lineNumberSkipValue !== undefined || lineNumberSetValue !== undefined)) {
     ensureLogicalLineCounts()
-    lineNumberPlan = resolveAdvancedLineNumberPlan(lineNumberSkipValue, lineNumberResetValue, sourceLogicalLineCount, highlightedLogicalLineCount)
+    lineNumberPlan = resolveAdvancedLineNumberPlan(lineNumberSkipValue, lineNumberSetValue, sourceLogicalLineCount, highlightedLogicalLineCount)
+  }
+  let lineNotePlan = null
+  if (!useHighlightPre && lineNotes && lineNotes.length) {
+    ensureLogicalLineCounts()
+    lineNotePlan = resolveLineNotesPlan(lineNotes, sourceLogicalLineCount, highlightedLogicalLineCount, lineNoteIdPrefix)
   }
   const needEmphasis = normalizedEmphasis.length > 0
   const needEndSpan = opt.lineEndSpanThreshold > 0
-  const useHighlightPre = opt.useHighlightPre && hasHighlightPre
 
   if (!useHighlightPre && commentMarkValue && sourceContent.indexOf(commentMarkValue) !== -1) {
     ensureLogicalLineCounts()
@@ -140,7 +151,7 @@ const renderFenceMarkup = (context, md, opt, slf) => {
     }
   }
 
-  if (!useHighlightPre && (needLineNumber || needEmphasis || needEndSpan || needComment)) {
+  if (!useHighlightPre && (needLineNumber || needEmphasis || needEndSpan || needComment || lineNotePlan)) {
     const splitStartedAt = timingEnabled ? getNowMs() : 0
     const nlIndex = content.indexOf('\n')
     const br = nlIndex > 0 && content[nlIndex - 1] === '\r' ? '\r\n' : '\n'
@@ -156,6 +167,7 @@ const renderFenceMarkup = (context, md, opt, slf) => {
       commentLines,
       commentLineClass,
       lineNumberPlan,
+      lineNotePlan,
     )
     if (timingEnabled) addTimingMs(timings, 'lineSplitMs', getNowMs() - splitStartedAt)
   }
@@ -165,11 +177,12 @@ const renderFenceMarkup = (context, md, opt, slf) => {
     renderer: 'markup',
     useHighlightPre,
     hasHighlightPre,
-    disabledFeatures: useHighlightPre ? ['setLineNumber', 'line-number-skip', 'line-number-reset', 'setEmphasizeLines', 'lineEndSpanThreshold', 'comment-mark', 'samp'] : [],
+    disabledFeatures: useHighlightPre ? markupPassthroughDisabledFeatures : [],
   }
   if (timingEnabled) decision.timings = finalizeFenceTimings(timings, fenceStartedAt)
   emitFenceDecision(opt, decision)
-  return `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>\n`
+  const preHtml = `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>`
+  return wrapFencePreWithLineNotes(preHtml, lineNotePlan)
 }
 
 export {

package/src/fence/render-shared.js

@@ -4,20 +4,36 @@ import {
   getInfoAttr,
   getLangFromClassAttr,
 } from '../utils/attr-utils.js'
+import {
+  getTokenLineNotes,
+} from './line-notes.js'
 
 const infoReg = /^([^{\s]*)(?:\s*\{(.*)\})?$/
 const tagReg = /<\/?([A-Za-z][A-Za-z0-9-]*)(?:\s+[^>]*?)?\/?\s*>/g
 const preLineTag = '<span class="pre-line">'
 const preLineNoNumberClass = 'pre-line-no-number'
+const preLineHasEndNoteClass = 'pre-line-has-end-note'
+const preLineContentClass = 'pre-line-content'
 const emphOpenTag = '<span class="pre-lines-emphasis">'
 const commentLineClass = 'pre-line-comment'
+const preWithLineNotesClass = 'pre-wrapper-line-notes'
+const lineNoteLayerClass = 'pre-line-note-layer'
+const lineNoteClass = 'pre-line-note'
 const closeTag = '</span>'
 const closeTagLen = closeTag.length
+const defaultPreLineTags = { open: preLineTag, close: closeTag }
 const preWrapStyle = 'white-space: pre-wrap; overflow-wrap: anywhere;'
 const voidTags = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'])
 const nonNegativeIntReg = /^\d+$/
 const positiveIntReg = /^[1-9]\d*$/
 
+const getLineNoteIdPrefix = (token, idx) => {
+  const tokenMap = token && Array.isArray(token.map) ? token.map : null
+  const mapStart = tokenMap && Number.isSafeInteger(tokenMap[0]) ? tokenMap[0] + 1 : 0
+  const tokenIndex = Number.isSafeInteger(idx) ? idx + 1 : 0
+  return `pre-line-note-${mapStart}-${tokenIndex}`
+}
+
 const getLineVisualLengthIgnoringTags = (line, threshold) => {
   let len = 0
   let inTag = false
@@ -89,6 +105,7 @@ const createCommonFenceOptionDefaults = (md) => {
 const finalizeCommonFenceOption = (opt) => {
   opt._sampReg = new RegExp('^(?:samp|' + opt.sampLang.split(',').join('|') + ')$')
   opt._attrOrderIndex = createAttrOrderIndexGetter(opt.attrsOrder || [])
+  opt._attrOrderRankCache = new Map()
   return opt
 }
 
@@ -115,6 +132,13 @@ const parsePositiveLineIndex = (val) => {
   return num
 }
 
+const escapeHtmlText = (value) => {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
 const getLogicalLineCount = (text) => {
   const str = String(text ?? '')
   if (!str) return 0
@@ -190,7 +214,7 @@ const normalizeEmphasisRanges = (emphasizeLines, maxLine) => {
   return normalized
 }
 
-const getLineNumberResetEntries = (attrVal) => {
+const getLineNumberSetEntries = (attrVal) => {
   const str = String(attrVal ?? '')
   if (!str) return []
   const result = []
@@ -200,9 +224,9 @@ const getLineNumberResetEntries = (attrVal) => {
     const colon = part.indexOf(':')
     if (colon === -1) continue
     const lineNumber = parsePositiveLineIndex(part.slice(0, colon).trim())
-    const resetNumber = parseStartNumber(part.slice(colon + 1).trim())
-    if (lineNumber == null || resetNumber == null) continue
-    result.push([lineNumber, resetNumber])
+    const setNumber = parseStartNumber(part.slice(colon + 1).trim())
+    if (lineNumber == null || setNumber == null) continue
+    result.push([lineNumber, setNumber])
   }
   return result
 }
@@ -218,59 +242,142 @@ const createSparseLineFlagMap = (ranges, maxLine) => {
   return flags
 }
 
-const createSparseLineResetMap = (entries, maxLine) => {
+const createSparseLineSetMap = (entries, maxLine, hidden) => {
   if (!entries || !entries.length || maxLine <= 0) return null
-  const resets = []
+  const sets = []
   let hasValue = false
   for (let i = 0; i < entries.length; i++) {
     const line = entries[i][0]
     const value = entries[i][1]
     if (!Number.isSafeInteger(line) || line <= 0 || line > maxLine) continue
-    resets[line - 1] = value
+    if (hidden && hidden[line - 1]) continue
+    sets[line - 1] = value
     hasValue = true
   }
-  return hasValue ? resets : null
+  return hasValue ? sets : null
 }
 
-const buildAdvancedLineNumberPlan = (skipRanges, resetEntries, sourceLineCount, renderedLineCount) => {
+const buildAdvancedLineNumberPlan = (skipRanges, setEntries, lineCount) => {
   const hasSkip = !!(skipRanges && skipRanges.length)
-  const hasReset = !!(resetEntries && resetEntries.length)
-  if (!hasSkip && !hasReset) return null
-  if (!Number.isSafeInteger(sourceLineCount) || sourceLineCount <= 0) return null
-  if (sourceLineCount !== renderedLineCount) return null
-  const hidden = hasSkip ? createSparseLineFlagMap(skipRanges, sourceLineCount) : null
-  const resets = hasReset ? createSparseLineResetMap(resetEntries, sourceLineCount) : null
-  if (!hidden && !resets) return null
-  return { hidden, resets }
+  const hasSet = !!(setEntries && setEntries.length)
+  if (!hasSkip && !hasSet) return null
+  const hidden = hasSkip ? createSparseLineFlagMap(skipRanges, lineCount) : null
+  const sets = hasSet ? createSparseLineSetMap(setEntries, lineCount, hidden) : null
+  if (!hidden && !sets) return null
+  return { hidden, sets }
 }
 
-const resolveAdvancedLineNumberPlan = (lineNumberSkipValue, lineNumberResetValue, sourceLineCount, renderedLineCount) => {
+const resolveAdvancedLineNumberPlan = (lineNumberSkipValue, lineNumberSetValue, sourceLineCount, renderedLineCount) => {
   const hasSkipValue = lineNumberSkipValue !== undefined
-  const hasResetValue = lineNumberResetValue !== undefined
-  if (!hasSkipValue && !hasResetValue) return null
+  const hasSetValue = lineNumberSetValue !== undefined
+  if (!hasSkipValue && !hasSetValue) return null
   if (!Number.isSafeInteger(sourceLineCount) || sourceLineCount <= 0) return null
   if (sourceLineCount !== renderedLineCount) return null
   const skipRanges = hasSkipValue ? getLineNumberSkipRanges(lineNumberSkipValue) : null
-  const resetEntries = hasResetValue ? getLineNumberResetEntries(lineNumberResetValue) : null
-  return buildAdvancedLineNumberPlan(skipRanges, resetEntries, sourceLineCount, renderedLineCount)
+  const setEntries = hasSetValue ? getLineNumberSetEntries(lineNumberSetValue) : null
+  return buildAdvancedLineNumberPlan(skipRanges, setEntries, sourceLineCount)
+}
+
+const createLineNotePlan = (lineNotes, maxLine, idPrefix) => {
+  if (!Array.isArray(lineNotes) || !lineNotes.length || maxLine <= 0) return null
+  const anchors = []
+  const items = []
+  const noteIdPrefix = String(idPrefix || 'pre-line-note')
+  let prevFrom = 0
+  let prevTo = 0
+  let needsSort = false
+  for (let i = 0; i < lineNotes.length; i++) {
+    const note = lineNotes[i]
+    if (!note || !Number.isSafeInteger(note.from) || !Number.isSafeInteger(note.to)) continue
+    let from = note.from
+    let to = note.to
+    if (from > to) {
+      const swap = from
+      from = to
+      to = swap
+    }
+    if (to < 1 || from > maxLine) continue
+    if (from < 1) from = 1
+    if (to > maxLine) to = maxLine
+    if (anchors[from - 1] !== undefined) return null
+    const lineCount = Number.isSafeInteger(note.lineCount) && note.lineCount > 0
+      ? note.lineCount
+      : Math.max(getLogicalLineCount(note.text), 1)
+    const item = {
+      from,
+      to,
+      label: from === to ? String(from) : `${from}-${to}`,
+      html: escapeHtmlText(note.text),
+      anchorName: `--pre-line-note-${from}`,
+      id: `${noteIdPrefix}-${from}`,
+      lineCount,
+      width: note.width || '',
+    }
+    anchors[from - 1] = item
+    items.push(item)
+    if (!needsSort && items.length > 1 && (from < prevFrom || (from === prevFrom && to < prevTo))) {
+      needsSort = true
+    }
+    prevFrom = from
+    prevTo = to
+  }
+  if (!items.length) return null
+
+  if (needsSort) items.sort((a, b) => a.from - b.from || a.to - b.to)
+  let canAnchor = true
+  let previousVisualEnd = 0
+  let overflowLines = 0
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    const visualEnd = item.from + item.lineCount - 1
+    if (item.from <= previousVisualEnd) canAnchor = false
+    if (visualEnd > maxLine) overflowLines = Math.max(overflowLines, visualEnd - maxLine)
+    previousVisualEnd = visualEnd
+  }
+
+  return {
+    anchors,
+    items,
+    canAnchor,
+    overflowLines,
+  }
 }
 
-const getPreLineOpenTag = (lineNumberPlan, lineIndex) => {
-  if (!lineNumberPlan) return preLineTag
-  const hidden = !!(lineNumberPlan.hidden && lineNumberPlan.hidden[lineIndex])
-  const resetNumber = lineNumberPlan.resets ? lineNumberPlan.resets[lineIndex] : undefined
-  if (!hidden && resetNumber == null) return preLineTag
+const resolveLineNotesPlan = (lineNotes, sourceLineCount, renderedLineCount, idPrefix) => {
+  if (!Array.isArray(lineNotes) || !lineNotes.length) return null
+  if (!Number.isSafeInteger(sourceLineCount) || sourceLineCount <= 0) return null
+  if (sourceLineCount !== renderedLineCount) return null
+  return createLineNotePlan(lineNotes, sourceLineCount, idPrefix)
+}
+
+const buildPreLineTags = (hidden, setNumber, lineNote) => {
+  if (!hidden && setNumber == null && !lineNote) return defaultPreLineTags
   let tag = '<span class="pre-line'
   if (hidden) tag += ' ' + preLineNoNumberClass
+  if (lineNote) tag += ' ' + preLineHasEndNoteClass
   tag += '"'
-  if (resetNumber != null) tag += ` style="counter-set:pre-line-number ${resetNumber};"`
-  return tag + '>'
+  if (setNumber != null) tag += ` style="counter-set:pre-line-number ${setNumber};"`
+  if (lineNote) {
+    tag += ` data-pre-line-note-from="${lineNote.from}"`
+    tag += ` data-pre-line-note-to="${lineNote.to}"`
+  }
+  tag += '>'
+  if (!lineNote) return { open: tag, close: closeTag }
+  const describedByAttr = lineNote.id ? ` aria-describedby="${lineNote.id}"` : ''
+  return {
+    open: `${tag}<span class="${preLineContentClass}" style="anchor-name:${lineNote.anchorName};"${describedByAttr}>`,
+    close: `${closeTag}${closeTag}`,
+  }
 }
 
-const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmphasis, needEndSpan, threshold, lineEndSpanClass, br, commentLines, commentClass, lineNumberPlan) => {
+const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmphasis, needEndSpan, threshold, lineEndSpanClass, br, commentLines, commentClass, lineNumberPlan, lineNotePlan) => {
   const lines = content.split(br)
   const max = lines.length
-  const hasDynamicLineNumberPlan = !!lineNumberPlan
+  const lineNumberHidden = lineNumberPlan ? lineNumberPlan.hidden : null
+  const lineNumberSets = lineNumberPlan ? lineNumberPlan.sets : null
+  const lineNoteAnchors = lineNotePlan ? lineNotePlan.anchors : null
+  const hasLineNotes = !!lineNoteAnchors
+  const needLineWrap = needLineNumber || hasLineNotes
   let emIdx = 0
   let emStart = -1
   let emEnd = -1
@@ -287,6 +394,9 @@ const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmp
     let line = lines[n]
     const notLastLine = n < max - 1
     const doComment = commentLines && commentLines[n]
+    const hidden = !!(lineNumberHidden && lineNumberHidden[n])
+    const setNumber = lineNumberSets ? lineNumberSets[n] : undefined
+    const lineNote = hasLineNotes ? lineNoteAnchors[n] : null
     let hasLt = false
     let hasLtChecked = false
 
@@ -310,7 +420,7 @@ const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmp
       }
     }
 
-    if (needLineNumber && notLastLine) {
+    if (needLineWrap && notLastLine) {
       if (!hasLtChecked) {
         hasLt = line.indexOf('<') !== -1
         hasLtChecked = true
@@ -340,8 +450,9 @@ const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmp
       line = `<span class="${commentClass}">` + line + closeTag
     }
 
-    if (needLineNumber && notLastLine) {
-      line = (hasDynamicLineNumberPlan ? getPreLineOpenTag(lineNumberPlan, n) : preLineTag) + line + closeTag
+    if (needLineWrap && notLastLine) {
+      const lineTags = buildPreLineTags(hidden, setNumber, lineNote)
+      line = lineTags.open + line + lineTags.close
     }
 
     if (needEmphasis && emIdx < emphasizeLines.length && emStart === n + 1) {
@@ -360,10 +471,33 @@ const splitFenceBlockToLines = (content, emphasizeLines, needLineNumber, needEmp
   return lines.join(br)
 }
 
+const renderLineNotesLayer = (lineNotePlan) => {
+  const items = lineNotePlan && lineNotePlan.items
+  if (!items || !items.length) return ''
+  let html = `<div class="${lineNoteLayerClass}">`
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i]
+    let style = `position-anchor:${item.anchorName};`
+    if (item.width) style += ` --line-note-width:${item.width};`
+    html += `<div id="${item.id}" class="${lineNoteClass}" role="note" data-pre-line-note-from="${item.from}" data-pre-line-note-to="${item.to}" data-pre-line-note-label="${item.label}" style="${style}">${item.html}</div>`
+  }
+  html += '</div>'
+  return html
+}
+
+const wrapFencePreWithLineNotes = (preHtml, lineNotePlan) => {
+  const items = lineNotePlan && lineNotePlan.items
+  if (!items || !items.length) return preHtml + '\n'
+  let attrs = ` class="${preWithLineNotesClass}"`
+  if (lineNotePlan.canAnchor) attrs += ' data-pre-line-notes-layout="anchor"'
+  if (lineNotePlan.overflowLines > 0) attrs += ` style="--pre-line-note-overflow-lines:${lineNotePlan.overflowLines};"`
+  return `<div${attrs}>${preHtml}${renderLineNotesLayer(lineNotePlan)}</div>\n`
+}
+
 const orderTokenAttrs = (token, opt) => {
   const attrs = token.attrs
   if (!attrs || attrs.length < 2) return
-  const rankCache = new Map()
+  const rankCache = opt._attrOrderRankCache || new Map()
   const getRank = (name) => {
     let rank = rankCache.get(name)
     if (rank === undefined) {
@@ -399,10 +533,12 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
   let startNumber = -1
   let emphasizeLines = []
   let lineNumberSkipValue
-  let lineNumberResetValue
+  let lineNumberSetValue
   let wrapEnabled = false
   let preWrapValue
   let commentMarkValue
+  const lineNotes = getTokenLineNotes(token)
+  const lineNoteIdPrefix = lineNotes && lineNotes.length ? getLineNoteIdPrefix(token, idx) : ''
   const attrNormalizeStartedAt = timingEnabled ? getNowMs() : 0
 
   if (token.attrs) {
@@ -412,7 +548,7 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
     let styleIndex = -1
     let dataPreCommentIndex = -1
     let dataPreLineNumberSkipIndex = -1
-    let dataPreLineNumberResetIndex = -1
+    let dataPreLineNumberSetIndex = -1
     let startValue
     let emphasisValue
     let styleValue
@@ -420,7 +556,7 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
     let sawStartAttr = false
     let sawEmphasisAttr = false
     let sawLineNumberSkipAttr = false
-    let sawLineNumberResetAttr = false
+    let sawLineNumberSetAttr = false
     const appendOrder = []
 
     for (const attr of token.attrs) {
@@ -469,11 +605,13 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
           lineNumberSkipValue = val
           newAttrs.push(attr)
           break
-        case 'data-pre-line-number-reset':
-          dataPreLineNumberResetIndex = newAttrs.length
-          lineNumberResetValue = val
+        case 'data-pre-line-number-set':
+          dataPreLineNumberSetIndex = newAttrs.length
+          lineNumberSetValue = val
           newAttrs.push(attr)
           break
+        case 'data-pre-line-number-reset':
+          break
         case 'em-lines':
         case 'emphasize-lines':
           if (opt.setEmphasizeLines) emphasizeLines = getEmphasizeLines(val)
@@ -498,13 +636,16 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
             sawLineNumberSkipAttr = true
           }
           break
+        case 'line-number-set':
+        case 'pre-line-number-set':
+          lineNumberSetValue = val
+          if (!sawLineNumberSetAttr) {
+            appendOrder.push('line-number-set')
+            sawLineNumberSetAttr = true
+          }
+          break
         case 'line-number-reset':
         case 'pre-line-number-reset':
-          lineNumberResetValue = val
-          if (!sawLineNumberResetAttr) {
-            appendOrder.push('line-number-reset')
-            sawLineNumberResetAttr = true
-          }
           break
         case 'data-pre-wrap':
           preWrapValue = val
@@ -523,7 +664,7 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
     if (emphasisValue !== undefined && dataPreEmphasisIndex >= 0) newAttrs[dataPreEmphasisIndex][1] = emphasisValue
     if (commentMarkValue !== undefined && dataPreCommentIndex >= 0) newAttrs[dataPreCommentIndex][1] = commentMarkValue
     if (lineNumberSkipValue !== undefined && dataPreLineNumberSkipIndex >= 0) newAttrs[dataPreLineNumberSkipIndex][1] = lineNumberSkipValue
-    if (lineNumberResetValue !== undefined && dataPreLineNumberResetIndex >= 0) newAttrs[dataPreLineNumberResetIndex][1] = lineNumberResetValue
+    if (lineNumberSetValue !== undefined && dataPreLineNumberSetIndex >= 0) newAttrs[dataPreLineNumberSetIndex][1] = lineNumberSetValue
 
     for (const kind of appendOrder) {
       if (kind === 'start' && dataPreStartIndex === -1 && startValue !== undefined) {
@@ -534,8 +675,8 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
         newAttrs.push(['data-pre-comment-mark', commentMarkValue])
       } else if (kind === 'line-number-skip' && dataPreLineNumberSkipIndex === -1 && lineNumberSkipValue !== undefined) {
         newAttrs.push(['data-pre-line-number-skip', lineNumberSkipValue])
-      } else if (kind === 'line-number-reset' && dataPreLineNumberResetIndex === -1 && lineNumberResetValue !== undefined) {
-        newAttrs.push(['data-pre-line-number-reset', lineNumberResetValue])
+      } else if (kind === 'line-number-set' && dataPreLineNumberSetIndex === -1 && lineNumberSetValue !== undefined) {
+        newAttrs.push(['data-pre-line-number-set', lineNumberSetValue])
       }
     }
 
@@ -553,6 +694,7 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
   }
 
   if (timingEnabled) addTimingMs(timings, 'attrNormalizeMs', getNowMs() - attrNormalizeStartedAt)
+  if (lineNotes && lineNotes.length) token.attrSet('data-pre-line-notes', 'true')
 
   return {
     token,
@@ -560,10 +702,12 @@ const prepareFenceRenderContext = (tokens, idx, opt) => {
     startNumber,
     emphasizeLines,
     lineNumberSkipValue,
-    lineNumberResetValue,
+    lineNumberSetValue,
     wrapEnabled,
     preWrapValue,
     commentMarkValue,
+    lineNotes,
+    lineNoteIdPrefix,
     timingEnabled,
     timings,
     fenceStartedAt,
@@ -586,5 +730,7 @@ export {
   preWrapStyle,
   prepareFenceRenderContext,
   resolveAdvancedLineNumberPlan,
+  resolveLineNotesPlan,
   splitFenceBlockToLines,
+  wrapFencePreWithLineNotes,
 }

package/THIRD_PARTY_NOTICES.md

@@ -1,56 +0,0 @@
-# Third-Party Notices
-
-This repository is licensed under MIT (see `LICENSE`), and also contains documentation assets derived from third-party themes.
-
-## highlight.js theme references used in docs
-
-Files:
-
-- `docs/default-highlight-theme.css`
-
-Source references:
-
-- `highlight.js` style family (GitHub / GitHub Dark)
-- Upstream paths (for reference):
-  - `node_modules/highlight.js/styles/github.css`
-  - `node_modules/highlight.js/styles/github-dark.css`
-
-Upstream license:
-
-- BSD 3-Clause License
-- Copyright (c) 2006, Ivan Sagalaev.
-
-Full upstream license text:
-
-```text
-BSD 3-Clause License
-
-Copyright (c) 2006, Ivan Sagalaev.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-* Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-```
-