@dogsbay/format-fluidtopics-markdown

Importer for the Fluid Topics Markdown export shape — e.g. the ServiceNow/ServiceNowDocs GitHub repo (Apache-2.0). Converts an FT Markdown repo into Dogsbay's universal contract (ExportPage[] + NavItem[]) via the shared TreeNode model, so every existing exporter/renderer consumes it unchanged.

Import-only. (Export back to Fluid Topics is not supported.)

The format it handles

A markdown/{publication}/**.md tree where:

• each publication's index.md has doc_type: toc and an indented Markdown link list (the authored sidebar); the README "List of publications" gives the top-level order;
• topic frontmatter carries DITA semantics — topic_type (concept / task / reference), title, description, locale, release, last_updated;
• bodies are dirty Markdown: embedded raw <table> / DITA nav-card grids, two link schemes (relative .md in bodies, absolute raw.githubusercontent URLs in TOCs), and omitted media (dangling relative image paths).

See the format analysis in dogsbay-research (content/formats/fluidtopics-markdown-format.md).

Usage

import { importFluidTopicsProject } from "@dogsbay/format-fluidtopics-markdown";

const { pages, nav } = await importFluidTopicsProject("/path/to/ServiceNowDocs", {
  hrefPrefix: "/docs",
});

Or via the format plugin (for CLI composition):

import { plugin } from "@dogsbay/format-fluidtopics-markdown/cli";
// plugin.name === "fluidtopics-markdown"; plugin.detectSource(path); plugin.import(...)

What it does

• Frontmatter → Dogsbay conventions (topic_type→type, last_updated→date, locale→lang, release→version); unknown keys preserved.
• Embedded HTML tables → structured table nodes; nav-card grids → cards nodes (title / description / icon / href).
• Links → resolved to routes from both the relative-.md and the absolute raw.githubusercontent schemes; unresolved hrefs are reported, not fatal.
• Nav → built from each publication's index.md TOC + the README order.

Status

Phase 1–3 scaffold (parser + importer + nav, tests green). Not yet wired into the CLI convert / a migrate-fluidtopics command, and media handling currently leaves icon/image paths untouched — see dogsbay-research/plans/format-fluidtopics-markdown.md.