@lincoln504/pi-research 1.7.1 → 1.7.2

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.7.1", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -18704,6 +18704,7 @@ var BOT_PATTERNS = [
 ];
 var IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
 var MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+var EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
 
 // src/web-research/types.ts
 var FETCH_LAYER_TIMEOUT = 1e4;
@@ -18924,6 +18925,51 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+var FRONT_MATTER_SLOTS = [
+  ["title", "meta-og:title", "meta-citation_title"],
+  ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+  ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+  [
+    "meta-article:published_time",
+    "meta-citation_publication_date",
+    "meta-citation_date",
+    "meta-dcterms.date",
+    "meta-dc.date",
+    "meta-date",
+    "meta-dcterms.created"
+  ],
+  ["meta-article:modified_time", "meta-dcterms.modified"]
+];
+var MAX_FRONT_MATTER_CHARS = 2e4;
+var FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -18937,7 +18983,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -18948,7 +18994,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {

package/dist/thread-worker.mjs

@@ -149,7 +149,7 @@ var init_user_agent = __esm({
 });
 
 // src/web-research/scraper-types.ts
-var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN;
+var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN, EMPTY_FRAGMENT_LINK_PATTERN;
 var init_scraper_types = __esm({
   "src/web-research/scraper-types.ts"() {
     "use strict";
@@ -215,6 +215,7 @@ var init_scraper_types = __esm({
     ];
     IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
     MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+    EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
   }
 });
 
@@ -1559,6 +1560,7 @@ var init_browser_error_utils = __esm({
 // src/web-research/scraper-utils.ts
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
+  cleanConvertedMarkdown: () => cleanConvertedMarkdown,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1569,7 +1571,9 @@ __export(scraper_utils_exports, {
   isBenignScrapeFailure: () => isBenignScrapeFailure,
   isSsrfBlockError: () => isSsrfBlockError,
   ssrfSafeLookup: () => ssrfSafeLookup,
+  stripEmptyFragmentLinks: () => stripEmptyFragmentLinks,
   stripImageLinks: () => stripImageLinks,
+  trimFrontMatter: () => trimFrontMatter,
   validateContent: () => validateContent,
   validateUrlForSSRF: () => validateUrlForSSRF,
   validateUrlForSSRFSync: () => validateUrlForSSRFSync
@@ -1785,6 +1789,34 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -1798,7 +1830,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -1809,7 +1841,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {
@@ -1848,7 +1880,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1858,6 +1890,23 @@ var init_scraper_utils = __esm({
     init_scraper_types();
     init_browser_error_utils();
     cachedSsrfFetcher = void 0;
+    FRONT_MATTER_SLOTS = [
+      ["title", "meta-og:title", "meta-citation_title"],
+      ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+      ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+      [
+        "meta-article:published_time",
+        "meta-citation_publication_date",
+        "meta-citation_date",
+        "meta-dcterms.date",
+        "meta-dc.date",
+        "meta-date",
+        "meta-dcterms.created"
+      ],
+      ["meta-article:modified_time", "meta-dcterms.modified"]
+    ];
+    MAX_FRONT_MATTER_CHARS = 2e4;
+    FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
   }
 });
 

package/docs/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.2] - 2026-09-27
+
+### Changed
+
+- **Scraped pages keep only the useful part of the converter's front matter.** The native converter turns every `<meta>` tag into a front-matter line: 54 lines on a GitHub page (analytics and error-reporting URLs, verification hashes, nonces, app ids), and on arXiv the abstract three times over. Nothing parses these lines; researchers read them and the knowledge store indexes them. `trimFrontMatter` (`src/web-research/scraper-utils.ts`) now keeps the title, description, author and publication/modification dates (first key present per slot: plain, Open Graph, citation or Dublin Core names) and drops the rest; a page with none of them loses the block. GitHub pages shrink by about 11%, arXiv abstract pages by about a third. Side effect: an empty page shell whose front matter alone used to pass the stub check is now treated as a stub, so the browser fallback gets a chance.
+- **Scraped pages no longer carry empty same-page links.** Documentation generators such as Quarto and nbdev put an empty anchor before every code line (`<a href="#cb2-1"></a>`) and next to headings; the native HTML→Markdown converter turned each into `[](#cb2-1)`, so every code block in a research scrape (and in the knowledge store) started each line with one. Both converters now drop links that have no text and point to the same page (`cleanConvertedMarkdown` in `src/web-research/scraper-utils.ts`, run after the existing image-link stripping so heading anchors that wrap an icon — GitHub's `[![](link.svg)](#title)` — go too). Links with text, and empty links to other pages, are kept. On an nbdev documentation page (fastcore.fast.ai/docments.html) this removes 583 such links, 16% of the scraped text.
+
 ## [1.7.1] - 2026-09-27
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/infrastructure/browser/thread-worker.mjs

@@ -149,7 +149,7 @@ var init_user_agent = __esm({
 });
 
 // src/web-research/scraper-types.ts
-var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN;
+var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN, EMPTY_FRAGMENT_LINK_PATTERN;
 var init_scraper_types = __esm({
   "src/web-research/scraper-types.ts"() {
     "use strict";
@@ -215,6 +215,7 @@ var init_scraper_types = __esm({
     ];
     IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
     MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+    EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
   }
 });
 
@@ -1559,6 +1560,7 @@ var init_browser_error_utils = __esm({
 // src/web-research/scraper-utils.ts
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
+  cleanConvertedMarkdown: () => cleanConvertedMarkdown,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1569,7 +1571,9 @@ __export(scraper_utils_exports, {
   isBenignScrapeFailure: () => isBenignScrapeFailure,
   isSsrfBlockError: () => isSsrfBlockError,
   ssrfSafeLookup: () => ssrfSafeLookup,
+  stripEmptyFragmentLinks: () => stripEmptyFragmentLinks,
   stripImageLinks: () => stripImageLinks,
+  trimFrontMatter: () => trimFrontMatter,
   validateContent: () => validateContent,
   validateUrlForSSRF: () => validateUrlForSSRF,
   validateUrlForSSRFSync: () => validateUrlForSSRFSync
@@ -1785,6 +1789,34 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -1798,7 +1830,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -1809,7 +1841,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {
@@ -1848,7 +1880,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1858,6 +1890,23 @@ var init_scraper_utils = __esm({
     init_scraper_types();
     init_browser_error_utils();
     cachedSsrfFetcher = void 0;
+    FRONT_MATTER_SLOTS = [
+      ["title", "meta-og:title", "meta-citation_title"],
+      ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+      ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+      [
+        "meta-article:published_time",
+        "meta-citation_publication_date",
+        "meta-citation_date",
+        "meta-dcterms.date",
+        "meta-dc.date",
+        "meta-date",
+        "meta-dcterms.created"
+      ],
+      ["meta-article:modified_time", "meta-dcterms.modified"]
+    ];
+    MAX_FRONT_MATTER_CHARS = 2e4;
+    FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
   }
 });
 

package/src/web-research/scraper-types.ts

@@ -54,6 +54,13 @@ export const BOT_PATTERNS: ReadonlyArray<[string, string]> = [
 
 export const IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
 export const MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+/**
+ * `[](#fragment)` — a link with no text to a spot on the same page (optional
+ * title). Documentation generators put one before every code line (Quarto,
+ * nbdev: `<a href="#cb2-1" aria-hidden="true"></a>`) and next to headings; the
+ * converters turn each into `[](#cb2-1)`, which carries no text.
+ */
+export const EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
 
 export type { ScrapeLayerResult } from './types.ts';
 

package/src/web-research/scraper-utils.ts

@@ -15,6 +15,7 @@ import {
   FILTERED_TAGS,
   IMAGE_LINK_PATTERN,
   MARKDOWN_IMAGE_PATTERN,
+  EMPTY_FRAGMENT_LINK_PATTERN,
   BOT_PATTERNS,
   INTERNAL_NETWORK_PATTERNS,
   type NativeHtmlToMarkdownModule,
@@ -485,6 +486,76 @@ function isMappedLoopback(ip: string): boolean {
   return mapped !== null && /^127\./.test(mapped);
 }
 
+/**
+ * Drop empty same-page links (`[](#cb2-1)`): per-line code anchors and heading
+ * anchors that documentation generators emit. They carry no text, but repeat on
+ * every code line and every heading, so they cost tokens and add noise to the
+ * knowledge store index. Links with text, and empty links to other pages, stay.
+ */
+export function stripEmptyFragmentLinks(markdown: string): string {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, '');
+}
+
+/**
+ * Front-matter keys kept by trimFrontMatter, one slot per piece of information;
+ * the first key present in a slot wins (the native converter prefixes <meta>
+ * names with `meta-`, keeping Open Graph / Dublin Core / citation prefixes).
+ */
+const FRONT_MATTER_SLOTS: ReadonlyArray<readonly string[]> = [
+  ['title', 'meta-og:title', 'meta-citation_title'],
+  ['meta-description', 'description', 'meta-og:description', 'meta-twitter:description'],
+  ['meta-author', 'meta-article:author', 'meta-citation_author', 'meta-dc.creator', 'meta-dcterms.creator'],
+  ['meta-article:published_time', 'meta-citation_publication_date', 'meta-citation_date', 'meta-dcterms.date',
+    'meta-dc.date', 'meta-date', 'meta-dcterms.created'],
+  ['meta-article:modified_time', 'meta-dcterms.modified'],
+];
+/** Front matter longer than this is not the converter's (e.g. a Markdown file's own); leave it. */
+const MAX_FRONT_MATTER_CHARS = 20_000;
+/** A front-matter entry starts with `key:`; other lines continue the previous value. */
+const FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+
+/**
+ * Trim the front matter the native converter builds from <meta> tags to the
+ * lines a reader can use: title, description, author, publication and
+ * modification date. The rest (analytics and error-reporting URLs, verification
+ * hashes, nonces, app ids, Open Graph / Twitter duplicates of the title and
+ * description, viewport, robots…) is noise: 54 lines on a GitHub page. Nothing
+ * in pi-research parses these lines. The block is dropped when none of the kept
+ * keys is present.
+ */
+export function trimFrontMatter(markdown: string): string {
+  if (!markdown.startsWith('---\n')) return markdown;
+  const close = markdown.indexOf('\n---\n', 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+
+  const entries: Array<{ key: string; lines: string[] }> = [];
+  for (const line of markdown.slice(4, close).split('\n')) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1]!.toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1]!.lines.push(line);
+  }
+  const kept: string[] = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== undefined);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, '');
+  return kept.length ? `---\n${kept.join('\n')}\n---\n\n${rest}` : rest;
+}
+
+/**
+ * Converter post-processing, shared by the native and the JS converter. The
+ * front matter is trimmed first. Images go before empty links: a heading anchor
+ * often wraps an icon (GitHub: `[![](link.svg)](#title)`) and only becomes an
+ * empty link once the image is gone. Removing a link that stood on its own line
+ * leaves extra blank lines, so they are collapsed again.
+ */
+export function cleanConvertedMarkdown(markdown: string): string {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
 /**
  * Strip image links from markdown
  */
@@ -511,7 +582,7 @@ export function createNativeMarkdownConverter(
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false,
     });
-    return stripImageLinks(result.content ?? '');
+    return cleanConvertedMarkdown(result.content ?? '');
   };
 }
 
@@ -527,7 +598,7 @@ export function createJsMarkdownConverter(): (html: string) => Promise<string> {
 
   return async (html: string): Promise<string> => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }