@bendyline/gezel-knowledge 1.2.1 → 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +14 -9
- package/dist/index.js +518 -70
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1052,7 +1052,7 @@ declare function createProfileEmbedder(profile: KnowledgeEmbeddingProfile, opts?
|
|
|
1052
1052
|
* files, never the disk, so an outline can be checked in a test without a
|
|
1053
1053
|
* tree on disk.
|
|
1054
1054
|
*/
|
|
1055
|
-
type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book';
|
|
1055
|
+
type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book' | 'docfx';
|
|
1056
1056
|
type OutlineFormat = Exclude<TableOfContentsFormat, 'folders' | 'hugo'>;
|
|
1057
1057
|
interface OutlineEntry {
|
|
1058
1058
|
/** Root-relative POSIX path of the Markdown file, extension included. */
|
|
@@ -1131,10 +1131,11 @@ declare function parseJupyterBookToc(doc: unknown, tocDir: string, files: readon
|
|
|
1131
1131
|
* gets the single root topic the compiler demands.
|
|
1132
1132
|
*
|
|
1133
1133
|
* A tree that already carries an outline keeps it: GitBook's `SUMMARY.md`,
|
|
1134
|
-
* an `mkdocs.yml` nav
|
|
1135
|
-
*
|
|
1136
|
-
*
|
|
1137
|
-
*
|
|
1134
|
+
* an `mkdocs.yml` nav, Jupyter Book's `_toc.yml` and docfx's per-folder
|
|
1135
|
+
* `toc.yml` files are read into the same topic tree (`outline.ts`,
|
|
1136
|
+
* `docfx.ts`), and Hugo's conventions — `_index.md` section pages,
|
|
1137
|
+
* `weight`, `draft` — are honored on top of the folders. A file an outline
|
|
1138
|
+
* omits stays in its folder, with a warning, so nothing is lost.
|
|
1138
1139
|
*
|
|
1139
1140
|
* Front matter carries what a documentation tree knows about itself: the
|
|
1140
1141
|
* title and summary, an explicit `id`, an `order` (the listing ordinal), a
|
|
@@ -1166,7 +1167,10 @@ interface TableOfContentsOptions {
|
|
|
1166
1167
|
/**
|
|
1167
1168
|
* The outline file for `gitbook` (`SUMMARY.md`), `mkdocs` (`mkdocs.yml`)
|
|
1168
1169
|
* and `jupyter-book` (`_toc.yml`), absolute or relative to the root. By
|
|
1169
|
-
* default the root is searched, and for mkdocs its parent as well.
|
|
1170
|
+
* default the root is searched, and for mkdocs its parent as well. For
|
|
1171
|
+
* `docfx` it is the entry TOC (a breadcrumb such as `bread/toc.yml`, or a
|
|
1172
|
+
* root `toc.yml`); by default docfx.json's `breadcrumb_path`, else the
|
|
1173
|
+
* root `toc.yml`.
|
|
1170
1174
|
*/
|
|
1171
1175
|
path?: string;
|
|
1172
1176
|
}
|
|
@@ -1192,7 +1196,7 @@ interface LoadMarkdownCatalogOptions {
|
|
|
1192
1196
|
publisherId: string;
|
|
1193
1197
|
catalogId: string;
|
|
1194
1198
|
};
|
|
1195
|
-
/** What to do with an image link whose file is missing (default `error`). */
|
|
1199
|
+
/** What to do with an image link whose file is missing (default `error`; `warn` for docfx). */
|
|
1196
1200
|
missingAssets?: 'error' | 'warn';
|
|
1197
1201
|
onWarning?: (message: string) => void;
|
|
1198
1202
|
}
|
|
@@ -1201,8 +1205,9 @@ declare function readMkdocsDocsDir(mkdocsPath: string): Promise<string>;
|
|
|
1201
1205
|
/**
|
|
1202
1206
|
* Which outline a tree carries: GitBook's `SUMMARY.md` or Jupyter Book's
|
|
1203
1207
|
* `_toc.yml` at the root, an `mkdocs.yml` at the root, the project folder
|
|
1204
|
-
* or the root's parent,
|
|
1205
|
-
* tree — else the
|
|
1208
|
+
* or the root's parent, a docfx project (`docfx.json` or a `toc.yml` at the
|
|
1209
|
+
* root), Hugo's `_index.md` section pages anywhere in the tree — else the
|
|
1210
|
+
* folders themselves.
|
|
1206
1211
|
*/
|
|
1207
1212
|
declare function detectTableOfContents(rootDir: string, projectDir?: string): Promise<TableOfContentsOptions>;
|
|
1208
1213
|
/**
|
package/dist/index.js
CHANGED
|
@@ -3817,52 +3817,19 @@ async function createProfileEmbedder(profile, opts = {}) {
|
|
|
3817
3817
|
// src/markdown-adapter/load.ts
|
|
3818
3818
|
import { existsSync } from "fs";
|
|
3819
3819
|
import { readFile as readFile3, readdir } from "fs/promises";
|
|
3820
|
-
import { basename, dirname as dirname3, isAbsolute as isAbsolute3, join as join6, posix as
|
|
3820
|
+
import { basename, dirname as dirname3, isAbsolute as isAbsolute3, join as join6, posix as posix3, relative as relative3, resolve as resolve4, sep } from "path";
|
|
3821
3821
|
import {
|
|
3822
3822
|
CatalogDocumentSchema,
|
|
3823
3823
|
KnowledgeDocumentIdSchema,
|
|
3824
3824
|
KnowledgeOrdinalSchema,
|
|
3825
|
+
MAX_KNOWLEDGE_TOPIC_DEPTH as MAX_KNOWLEDGE_TOPIC_DEPTH2,
|
|
3825
3826
|
assetExtension as assetExtension3,
|
|
3826
3827
|
formatKnowledgeUri,
|
|
3827
3828
|
topicSortKeyForOrder
|
|
3828
3829
|
} from "@bendyline/gezk";
|
|
3829
3830
|
|
|
3830
|
-
// src/markdown-adapter/
|
|
3831
|
-
import {
|
|
3832
|
-
var FRONTMATTER_MAX_BYTES = 64 * 1024;
|
|
3833
|
-
var OUTLINE_MAX_BYTES = 1024 * 1024;
|
|
3834
|
-
function parseYaml(text, opts) {
|
|
3835
|
-
const maxBytes = opts.maxBytes ?? FRONTMATTER_MAX_BYTES;
|
|
3836
|
-
if (Buffer.byteLength(text, "utf8") > maxBytes) {
|
|
3837
|
-
throw new Error(`${opts.what} exceeds ${maxBytes} bytes`);
|
|
3838
|
-
}
|
|
3839
|
-
const doc = parseDocument(text, {
|
|
3840
|
-
version: "1.2",
|
|
3841
|
-
schema: "core",
|
|
3842
|
-
uniqueKeys: true,
|
|
3843
|
-
logLevel: "silent"
|
|
3844
|
-
});
|
|
3845
|
-
const problem = doc.errors[0] ?? (opts.tolerateUnknownTags ? void 0 : doc.warnings[0]);
|
|
3846
|
-
if (problem) throw new Error(`${opts.what}: ${problem.message.split("\n")[0]}`);
|
|
3847
|
-
return doc.toJS({ maxAliasCount: opts.maxAliasCount ?? 0 });
|
|
3848
|
-
}
|
|
3849
|
-
var OPEN = /^---[ \t]*\r?\n/;
|
|
3850
|
-
var CLOSE = /^(?:---|\.\.\.)[ \t]*$/;
|
|
3851
|
-
function parseMarkdownFrontMatter(source) {
|
|
3852
|
-
const open = OPEN.exec(source);
|
|
3853
|
-
if (!open) return { data: {}, body: source };
|
|
3854
|
-
const lines = source.slice(open[0].length).split(/\r?\n/);
|
|
3855
|
-
const closeAt = lines.findIndex((line) => CLOSE.test(line));
|
|
3856
|
-
if (closeAt === -1) throw new Error("front matter is not closed with ---");
|
|
3857
|
-
const yamlText = lines.slice(0, closeAt).join("\n");
|
|
3858
|
-
const body = lines.slice(closeAt + 1).join("\n");
|
|
3859
|
-
const parsed = parseYaml(yamlText, { what: "front matter" });
|
|
3860
|
-
if (parsed === null || parsed === void 0) return { data: {}, body };
|
|
3861
|
-
if (typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
3862
|
-
throw new Error("front matter must be a mapping");
|
|
3863
|
-
}
|
|
3864
|
-
return { data: parsed, body };
|
|
3865
|
-
}
|
|
3831
|
+
// src/markdown-adapter/docfx.ts
|
|
3832
|
+
import { posix as posix2 } from "path";
|
|
3866
3833
|
|
|
3867
3834
|
// src/markdown-adapter/outline.ts
|
|
3868
3835
|
import { posix } from "path";
|
|
@@ -4159,14 +4126,400 @@ function parseJupyterBookToc(doc, tocDir, files, tocFile = "_toc.yml") {
|
|
|
4159
4126
|
return outline;
|
|
4160
4127
|
}
|
|
4161
4128
|
|
|
4129
|
+
// src/markdown-adapter/docfx.ts
|
|
4130
|
+
var HAS_SCHEME2 = /^[a-z][a-z0-9+.-]*:/i;
|
|
4131
|
+
var MARKDOWN_EXT2 = /\.(md|markdown)$/i;
|
|
4132
|
+
var TOC_FILE = /^toc\.(ya?ml|json|md)$/i;
|
|
4133
|
+
var LANDING_PAGE = /(^|\/)index\.(ya?ml|md)$/i;
|
|
4134
|
+
var WARNING_EXAMPLES = 5;
|
|
4135
|
+
function isRecord2(value) {
|
|
4136
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
4137
|
+
}
|
|
4138
|
+
function normalizeFolder(value) {
|
|
4139
|
+
if (typeof value !== "string") return "";
|
|
4140
|
+
const cleaned = posix2.normalize(value.replace(/\\/g, "/")).replace(/^\.?\/+|\/+$/g, "");
|
|
4141
|
+
return cleaned === "." ? "" : cleaned;
|
|
4142
|
+
}
|
|
4143
|
+
function dirOf(file) {
|
|
4144
|
+
const dir = posix2.dirname(file);
|
|
4145
|
+
return dir === "." ? "" : dir;
|
|
4146
|
+
}
|
|
4147
|
+
function parentOf(dir) {
|
|
4148
|
+
return dir === "" ? null : dirOf(dir);
|
|
4149
|
+
}
|
|
4150
|
+
function isUnder(file, dir) {
|
|
4151
|
+
return dir === "" || file.startsWith(`${dir}/`);
|
|
4152
|
+
}
|
|
4153
|
+
function escapeRegExp(text) {
|
|
4154
|
+
return text.replace(/[.+^$()|[\]\\]/g, "\\$&");
|
|
4155
|
+
}
|
|
4156
|
+
function docfxGlob(pattern) {
|
|
4157
|
+
const p = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
|
|
4158
|
+
let source = "";
|
|
4159
|
+
for (let i = 0; i < p.length; i++) {
|
|
4160
|
+
const ch = p[i];
|
|
4161
|
+
if (ch === "*") {
|
|
4162
|
+
if (p[i + 1] === "*") {
|
|
4163
|
+
if (p[i + 2] === "/") {
|
|
4164
|
+
source += "(?:.*/)?";
|
|
4165
|
+
i += 2;
|
|
4166
|
+
} else {
|
|
4167
|
+
source += ".*";
|
|
4168
|
+
i += 1;
|
|
4169
|
+
}
|
|
4170
|
+
} else source += "[^/]*";
|
|
4171
|
+
} else if (ch === "?") {
|
|
4172
|
+
source += "[^/]";
|
|
4173
|
+
} else if (ch === "{" && p.indexOf("}", i) > i) {
|
|
4174
|
+
const close = p.indexOf("}", i);
|
|
4175
|
+
source += `(?:${p.slice(i + 1, close).split(",").map(escapeRegExp).join("|")})`;
|
|
4176
|
+
i = close;
|
|
4177
|
+
} else {
|
|
4178
|
+
source += escapeRegExp(ch);
|
|
4179
|
+
}
|
|
4180
|
+
}
|
|
4181
|
+
return new RegExp(`^${source}$`, "i");
|
|
4182
|
+
}
|
|
4183
|
+
function globList(value) {
|
|
4184
|
+
const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
|
|
4185
|
+
return list.filter((g) => typeof g === "string" && g.trim() !== "").map(docfxGlob);
|
|
4186
|
+
}
|
|
4187
|
+
function parseDocfxJson(config, configFile = "docfx.json") {
|
|
4188
|
+
if (!isRecord2(config)) throw new Error(`${configFile}: not a JSON object`);
|
|
4189
|
+
const build = isRecord2(config.build) ? config.build : {};
|
|
4190
|
+
const content = [];
|
|
4191
|
+
for (const group of Array.isArray(build.content) ? build.content : []) {
|
|
4192
|
+
if (!isRecord2(group)) continue;
|
|
4193
|
+
const include = globList(group.files);
|
|
4194
|
+
if (include.length === 0) continue;
|
|
4195
|
+
content.push({
|
|
4196
|
+
src: normalizeFolder(group.src),
|
|
4197
|
+
dest: normalizeFolder(group.dest),
|
|
4198
|
+
include,
|
|
4199
|
+
exclude: globList(group.exclude)
|
|
4200
|
+
});
|
|
4201
|
+
}
|
|
4202
|
+
const meta = isRecord2(build.globalMetadata) ? build.globalMetadata : {};
|
|
4203
|
+
const breadcrumb = meta.breadcrumb_path;
|
|
4204
|
+
return {
|
|
4205
|
+
content,
|
|
4206
|
+
...typeof breadcrumb === "string" && breadcrumb.trim() ? { breadcrumbPath: breadcrumb.trim() } : {}
|
|
4207
|
+
};
|
|
4208
|
+
}
|
|
4209
|
+
function docfxPublishes(project, file) {
|
|
4210
|
+
if (project.content.length === 0) return true;
|
|
4211
|
+
return project.content.some((group) => {
|
|
4212
|
+
if (!isUnder(file, group.src)) return false;
|
|
4213
|
+
const rel = group.src === "" ? file : file.slice(group.src.length + 1);
|
|
4214
|
+
return group.include.some((r) => r.test(rel)) && !group.exclude.some((r) => r.test(rel));
|
|
4215
|
+
});
|
|
4216
|
+
}
|
|
4217
|
+
function tocItems(doc) {
|
|
4218
|
+
if (Array.isArray(doc)) return doc;
|
|
4219
|
+
if (isRecord2(doc) && Array.isArray(doc.items)) return doc.items;
|
|
4220
|
+
return [];
|
|
4221
|
+
}
|
|
4222
|
+
function isBreadcrumbToc(doc) {
|
|
4223
|
+
let tocHref = false;
|
|
4224
|
+
const visit = (items) => {
|
|
4225
|
+
for (const item of items) {
|
|
4226
|
+
if (!isRecord2(item)) continue;
|
|
4227
|
+
if (typeof item.href === "string") return false;
|
|
4228
|
+
if (typeof item.tocHref === "string") tocHref = true;
|
|
4229
|
+
if (Array.isArray(item.items) && !visit(item.items)) return false;
|
|
4230
|
+
}
|
|
4231
|
+
return true;
|
|
4232
|
+
};
|
|
4233
|
+
return visit(tocItems(doc)) && tocHref;
|
|
4234
|
+
}
|
|
4235
|
+
function basePrefixes(url) {
|
|
4236
|
+
const segments = url.split("/").filter(Boolean);
|
|
4237
|
+
const out = ["/"];
|
|
4238
|
+
for (let i = 1; i < segments.length; i++) out.push(`/${segments.slice(0, i).join("/")}/`);
|
|
4239
|
+
return out;
|
|
4240
|
+
}
|
|
4241
|
+
function parseDocfxToc(input) {
|
|
4242
|
+
const outline = {
|
|
4243
|
+
format: "docfx",
|
|
4244
|
+
root: newOutlineTopic(""),
|
|
4245
|
+
consumed: input.files.filter((file) => TOC_FILE.test(posix2.basename(file))),
|
|
4246
|
+
warnings: []
|
|
4247
|
+
};
|
|
4248
|
+
const known = new Set(input.files.map((file) => file.normalize("NFC")));
|
|
4249
|
+
const groups = input.project?.content.length ? [...input.project.content].sort((a, b) => b.dest.length - a.dest.length) : [{ src: "", dest: "", include: [], exclude: [] }];
|
|
4250
|
+
const tocByDir = /* @__PURE__ */ new Map();
|
|
4251
|
+
for (const file of [...input.tocs.keys()].sort()) {
|
|
4252
|
+
if (/\.ya?ml$/i.test(file) && !tocByDir.has(dirOf(file))) tocByDir.set(dirOf(file), file);
|
|
4253
|
+
}
|
|
4254
|
+
const sourcesOf = (sitePath) => {
|
|
4255
|
+
const out = [];
|
|
4256
|
+
for (const group of groups) {
|
|
4257
|
+
if (group.dest !== "" && sitePath !== group.dest && !sitePath.startsWith(`${group.dest}/`))
|
|
4258
|
+
continue;
|
|
4259
|
+
const rest = sitePath.slice(group.dest.length).replace(/^\/+/, "");
|
|
4260
|
+
out.push(group.src && rest ? `${group.src}/${rest}` : group.src || rest);
|
|
4261
|
+
}
|
|
4262
|
+
return out;
|
|
4263
|
+
};
|
|
4264
|
+
const tocAt = (path) => {
|
|
4265
|
+
const trimmed = path.replace(/\/+$/, "");
|
|
4266
|
+
return TOC_FILE.test(posix2.basename(trimmed)) ? tocByDir.get(dirOf(trimmed)) : tocByDir.get(trimmed);
|
|
4267
|
+
};
|
|
4268
|
+
const pageAt = (path) => {
|
|
4269
|
+
const candidates = path === "" || path.endsWith("/") ? [`${path}index.md`] : MARKDOWN_EXT2.test(path) ? [path] : [`${path}.md`, `${path}/index.md`];
|
|
4270
|
+
return candidates.find((candidate) => known.has(candidate.normalize("NFC")));
|
|
4271
|
+
};
|
|
4272
|
+
const resolveSite = (url, base2) => {
|
|
4273
|
+
const path = url.replace(/[?#].*$/, "");
|
|
4274
|
+
let below;
|
|
4275
|
+
if (`${path}/` === base2) below = "";
|
|
4276
|
+
else if (path.startsWith(base2)) below = path.slice(base2.length);
|
|
4277
|
+
else return null;
|
|
4278
|
+
for (const source of sourcesOf(below)) {
|
|
4279
|
+
const page = pageAt(source);
|
|
4280
|
+
if (page) return { kind: "page", file: page };
|
|
4281
|
+
const toc = tocAt(source);
|
|
4282
|
+
if (toc) return { kind: "toc", file: toc };
|
|
4283
|
+
}
|
|
4284
|
+
return null;
|
|
4285
|
+
};
|
|
4286
|
+
let entry = input.entry;
|
|
4287
|
+
let base;
|
|
4288
|
+
const breadcrumb = input.project?.breadcrumbPath;
|
|
4289
|
+
if (!entry && breadcrumb) {
|
|
4290
|
+
for (const candidate of basePrefixes(breadcrumb)) {
|
|
4291
|
+
const target = resolveSite(breadcrumb, candidate);
|
|
4292
|
+
if (target?.kind === "toc") {
|
|
4293
|
+
entry = target.file;
|
|
4294
|
+
base = candidate;
|
|
4295
|
+
break;
|
|
4296
|
+
}
|
|
4297
|
+
}
|
|
4298
|
+
if (!entry) {
|
|
4299
|
+
outline.warnings.push(
|
|
4300
|
+
`docfx.json: breadcrumb_path '${breadcrumb}' names no toc.yml in the tree; ignored`
|
|
4301
|
+
);
|
|
4302
|
+
}
|
|
4303
|
+
}
|
|
4304
|
+
entry ??= tocByDir.get("");
|
|
4305
|
+
if (entry && base === void 0) {
|
|
4306
|
+
const urls = [];
|
|
4307
|
+
const collect = (items) => {
|
|
4308
|
+
for (const item of items) {
|
|
4309
|
+
if (!isRecord2(item)) continue;
|
|
4310
|
+
for (const key of ["tocHref", "topicHref", "href"]) {
|
|
4311
|
+
const value = item[key];
|
|
4312
|
+
if (typeof value === "string" && value.startsWith("/") && !value.startsWith("//")) {
|
|
4313
|
+
urls.push(value);
|
|
4314
|
+
}
|
|
4315
|
+
}
|
|
4316
|
+
if (Array.isArray(item.items)) collect(item.items);
|
|
4317
|
+
}
|
|
4318
|
+
};
|
|
4319
|
+
collect(tocItems(input.tocs.get(entry)));
|
|
4320
|
+
let best = { base: "/", hits: 0 };
|
|
4321
|
+
for (const candidate of [...new Set(urls.flatMap(basePrefixes))].sort(
|
|
4322
|
+
(a, b) => a.length - b.length
|
|
4323
|
+
)) {
|
|
4324
|
+
const hits = urls.filter((url) => resolveSite(url, candidate) !== null).length;
|
|
4325
|
+
if (hits > best.hits) best = { base: candidate, hits };
|
|
4326
|
+
}
|
|
4327
|
+
base = best.base;
|
|
4328
|
+
}
|
|
4329
|
+
const siteBase = base ?? "/";
|
|
4330
|
+
const classify = (href, tocDir) => {
|
|
4331
|
+
const value = href.trim();
|
|
4332
|
+
if (value === "" || value.startsWith("#") || HAS_SCHEME2.test(value) || value.startsWith("//"))
|
|
4333
|
+
return null;
|
|
4334
|
+
if (value.startsWith("/")) return resolveSite(value, siteBase);
|
|
4335
|
+
const path = resolveOutlinePath(tocDir, value);
|
|
4336
|
+
if (path === null) return null;
|
|
4337
|
+
if (MARKDOWN_EXT2.test(path)) return { kind: "page", file: path };
|
|
4338
|
+
const toc = tocAt(path);
|
|
4339
|
+
return toc ? { kind: "toc", file: toc } : null;
|
|
4340
|
+
};
|
|
4341
|
+
const crossLinks = /* @__PURE__ */ new WeakSet();
|
|
4342
|
+
const included = /* @__PURE__ */ new Set();
|
|
4343
|
+
const homes = /* @__PURE__ */ new Map();
|
|
4344
|
+
const pageEntry = (file, tocDir) => {
|
|
4345
|
+
const entry2 = { file };
|
|
4346
|
+
if (!isUnder(file, tocDir)) crossLinks.add(entry2);
|
|
4347
|
+
return entry2;
|
|
4348
|
+
};
|
|
4349
|
+
const walkItems = (items, tocFile, container, followTocHref) => {
|
|
4350
|
+
const tocDir = dirOf(tocFile);
|
|
4351
|
+
for (const item of items) {
|
|
4352
|
+
if (!isRecord2(item)) continue;
|
|
4353
|
+
const name = typeof item.name === "string" ? item.name.trim() : "";
|
|
4354
|
+
const href = typeof item.href === "string" ? classify(item.href, tocDir) : null;
|
|
4355
|
+
const topicHref = typeof item.topicHref === "string" ? classify(item.topicHref, tocDir) : null;
|
|
4356
|
+
const tocHref = followTocHref && typeof item.tocHref === "string" ? classify(item.tocHref, tocDir) : null;
|
|
4357
|
+
const page = [href, topicHref].find((target) => target?.kind === "page");
|
|
4358
|
+
const nested = [href, tocHref].find(
|
|
4359
|
+
(target) => target?.kind === "toc" && !included.has(target.file)
|
|
4360
|
+
);
|
|
4361
|
+
const children = Array.isArray(item.items) && item.items.length > 0 ? item.items : null;
|
|
4362
|
+
if (!nested && !children) {
|
|
4363
|
+
if (page) container.entries.push(pageEntry(page.file, tocDir));
|
|
4364
|
+
continue;
|
|
4365
|
+
}
|
|
4366
|
+
const topic = newOutlineTopic(
|
|
4367
|
+
name || (nested ? titleFromFolderName(posix2.basename(dirOf(nested.file))) : "Untitled")
|
|
4368
|
+
);
|
|
4369
|
+
if (!name && page) topic.titleFromFile = page.file;
|
|
4370
|
+
if (page) topic.entries.push(pageEntry(page.file, tocDir));
|
|
4371
|
+
if (nested) includeToc(nested.file, topic, false);
|
|
4372
|
+
if (children) walkItems(children, tocFile, topic, followTocHref);
|
|
4373
|
+
container.children.push(topic);
|
|
4374
|
+
}
|
|
4375
|
+
};
|
|
4376
|
+
const includeToc = (file, container, followTocHref) => {
|
|
4377
|
+
if (included.has(file)) return;
|
|
4378
|
+
included.add(file);
|
|
4379
|
+
const dir = dirOf(file);
|
|
4380
|
+
if (container !== outline.root && !homes.has(dir)) homes.set(dir, container);
|
|
4381
|
+
walkItems(tocItems(input.tocs.get(file)), file, container, followTocHref);
|
|
4382
|
+
};
|
|
4383
|
+
const homeOf = (dir) => {
|
|
4384
|
+
for (let d = dir; d !== null; d = parentOf(d)) {
|
|
4385
|
+
const home = homes.get(d);
|
|
4386
|
+
if (home) return home;
|
|
4387
|
+
}
|
|
4388
|
+
return void 0;
|
|
4389
|
+
};
|
|
4390
|
+
if (entry) {
|
|
4391
|
+
outline.entry = entry;
|
|
4392
|
+
includeToc(entry, outline.root, true);
|
|
4393
|
+
}
|
|
4394
|
+
const lone = outline.root.entries.length === 0 && outline.root.children.length === 1 ? outline.root.children[0] : void 0;
|
|
4395
|
+
const top = lone ?? outline.root;
|
|
4396
|
+
const orphans = [...input.tocs.keys()].filter((file) => !included.has(file) && /\.ya?ml$/i.test(file)).sort((a, b) => a.split("/").length - b.split("/").length || (a < b ? -1 : a > b ? 1 : 0));
|
|
4397
|
+
for (const file of orphans) {
|
|
4398
|
+
if (included.has(file)) continue;
|
|
4399
|
+
const doc = input.tocs.get(file);
|
|
4400
|
+
if (isBreadcrumbToc(doc)) continue;
|
|
4401
|
+
const parent = parentOf(dirOf(file));
|
|
4402
|
+
const topic = newOutlineTopic(orphanTopicName(file, doc));
|
|
4403
|
+
((parent === null ? void 0 : homeOf(parent)) ?? top).children.push(topic);
|
|
4404
|
+
includeToc(file, topic, false);
|
|
4405
|
+
}
|
|
4406
|
+
const listed = /* @__PURE__ */ new Set();
|
|
4407
|
+
const collectListed = (topic) => {
|
|
4408
|
+
for (const entry2 of topic.entries) {
|
|
4409
|
+
if (!crossLinks.has(entry2)) listed.add(entry2.file.normalize("NFC"));
|
|
4410
|
+
}
|
|
4411
|
+
topic.children.forEach(collectListed);
|
|
4412
|
+
};
|
|
4413
|
+
collectListed(outline.root);
|
|
4414
|
+
const placed = /* @__PURE__ */ new Set();
|
|
4415
|
+
const missing = [];
|
|
4416
|
+
const duplicates = [];
|
|
4417
|
+
const settle = (topic) => {
|
|
4418
|
+
topic.entries = topic.entries.filter((entry2) => {
|
|
4419
|
+
const key = entry2.file.normalize("NFC");
|
|
4420
|
+
if (!known.has(key)) {
|
|
4421
|
+
missing.push(entry2.file);
|
|
4422
|
+
return false;
|
|
4423
|
+
}
|
|
4424
|
+
if (crossLinks.has(entry2) && listed.has(key)) return false;
|
|
4425
|
+
if (placed.has(key)) {
|
|
4426
|
+
if (!crossLinks.has(entry2)) duplicates.push(entry2.file);
|
|
4427
|
+
return false;
|
|
4428
|
+
}
|
|
4429
|
+
placed.add(key);
|
|
4430
|
+
return true;
|
|
4431
|
+
});
|
|
4432
|
+
topic.children.forEach(settle);
|
|
4433
|
+
};
|
|
4434
|
+
settle(outline.root);
|
|
4435
|
+
const consumed = new Set(outline.consumed.map((file) => file.normalize("NFC")));
|
|
4436
|
+
const homed = [];
|
|
4437
|
+
for (const file of input.files) {
|
|
4438
|
+
const key = file.normalize("NFC");
|
|
4439
|
+
if (placed.has(key) || consumed.has(key)) continue;
|
|
4440
|
+
const home = homeOf(dirOf(file));
|
|
4441
|
+
if (!home) continue;
|
|
4442
|
+
home.entries.push({ file });
|
|
4443
|
+
homed.push(file);
|
|
4444
|
+
}
|
|
4445
|
+
if (lone) {
|
|
4446
|
+
outline.root.entries = lone.entries;
|
|
4447
|
+
outline.root.children = lone.children;
|
|
4448
|
+
}
|
|
4449
|
+
assignOutlineOrders(outline.root);
|
|
4450
|
+
const report = (files, what) => {
|
|
4451
|
+
if (files.length === 0) return;
|
|
4452
|
+
const named = files.slice(0, WARNING_EXAMPLES).join(", ");
|
|
4453
|
+
const more = files.length > WARNING_EXAMPLES ? `, and ${files.length - WARNING_EXAMPLES} more` : "";
|
|
4454
|
+
outline.warnings.push(`${files.length} ${what}: ${named}${more}`);
|
|
4455
|
+
};
|
|
4456
|
+
report(
|
|
4457
|
+
[...new Set(missing)],
|
|
4458
|
+
"pages named by a toc.yml are not among the published Markdown files"
|
|
4459
|
+
);
|
|
4460
|
+
report([...new Set(duplicates)], "pages are listed more than once; the first place wins");
|
|
4461
|
+
report(homed, "pages are in no toc.yml; filed with their folder's section");
|
|
4462
|
+
return outline;
|
|
4463
|
+
}
|
|
4464
|
+
function orphanTopicName(file, doc) {
|
|
4465
|
+
for (const item of tocItems(doc)) {
|
|
4466
|
+
if (!isRecord2(item) || typeof item.name !== "string" || typeof item.href !== "string") continue;
|
|
4467
|
+
if (!LANDING_PAGE.test(item.href.replace(/[?#].*$/, ""))) continue;
|
|
4468
|
+
const name = item.name.trim().replace(/\s+(documentation|docs)$/i, "").trim();
|
|
4469
|
+
if (name) return name;
|
|
4470
|
+
}
|
|
4471
|
+
const folder = posix2.basename(dirOf(file));
|
|
4472
|
+
return folder ? titleFromFolderName(folder) : "Documentation";
|
|
4473
|
+
}
|
|
4474
|
+
|
|
4475
|
+
// src/markdown-adapter/frontmatter.ts
|
|
4476
|
+
import { parseDocument } from "yaml";
|
|
4477
|
+
var FRONTMATTER_MAX_BYTES = 64 * 1024;
|
|
4478
|
+
var OUTLINE_MAX_BYTES = 1024 * 1024;
|
|
4479
|
+
function parseYaml(text, opts) {
|
|
4480
|
+
const maxBytes = opts.maxBytes ?? FRONTMATTER_MAX_BYTES;
|
|
4481
|
+
if (Buffer.byteLength(text, "utf8") > maxBytes) {
|
|
4482
|
+
throw new Error(`${opts.what} exceeds ${maxBytes} bytes`);
|
|
4483
|
+
}
|
|
4484
|
+
const doc = parseDocument(text, {
|
|
4485
|
+
version: "1.2",
|
|
4486
|
+
schema: "core",
|
|
4487
|
+
uniqueKeys: true,
|
|
4488
|
+
logLevel: "silent"
|
|
4489
|
+
});
|
|
4490
|
+
const problem = doc.errors[0] ?? (opts.tolerateUnknownTags ? void 0 : doc.warnings[0]);
|
|
4491
|
+
if (problem) throw new Error(`${opts.what}: ${problem.message.split("\n")[0]}`);
|
|
4492
|
+
return doc.toJS({ maxAliasCount: opts.maxAliasCount ?? 0 });
|
|
4493
|
+
}
|
|
4494
|
+
var OPEN = /^---[ \t]*\r?\n/;
|
|
4495
|
+
var CLOSE = /^(?:---|\.\.\.)[ \t]*$/;
|
|
4496
|
+
function parseMarkdownFrontMatter(source) {
|
|
4497
|
+
const open = OPEN.exec(source);
|
|
4498
|
+
if (!open) return { data: {}, body: source };
|
|
4499
|
+
const lines = source.slice(open[0].length).split(/\r?\n/);
|
|
4500
|
+
const closeAt = lines.findIndex((line) => CLOSE.test(line));
|
|
4501
|
+
if (closeAt === -1) throw new Error("front matter is not closed with ---");
|
|
4502
|
+
const yamlText = lines.slice(0, closeAt).join("\n");
|
|
4503
|
+
const body = lines.slice(closeAt + 1).join("\n");
|
|
4504
|
+
const parsed = parseYaml(yamlText, { what: "front matter" });
|
|
4505
|
+
if (parsed === null || parsed === void 0) return { data: {}, body };
|
|
4506
|
+
if (typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
4507
|
+
throw new Error("front matter must be a mapping");
|
|
4508
|
+
}
|
|
4509
|
+
return { data: parsed, body };
|
|
4510
|
+
}
|
|
4511
|
+
|
|
4162
4512
|
// src/markdown-adapter/load.ts
|
|
4163
4513
|
var ROOT_TOPIC_ID = "general";
|
|
4164
4514
|
var SUMMARY_MAX_CHARS = 280;
|
|
4165
4515
|
var TOPIC_SIDECAR = "_topic.yaml";
|
|
4166
4516
|
var HUGO_SECTION_PAGE = "_index";
|
|
4517
|
+
var DOCFX_JSON = "docfx.json";
|
|
4518
|
+
var WARNING_EXAMPLES2 = 20;
|
|
4167
4519
|
var SECTION_PAGE_ORDINAL = -2147483648;
|
|
4168
4520
|
var RESERVED_KEYS = /* @__PURE__ */ new Set(["title", "summary", "aliases", "id", "order", "subcategory"]);
|
|
4169
|
-
function readFrontMatter(raw, file,
|
|
4521
|
+
function readFrontMatter(raw, file, conventions) {
|
|
4522
|
+
const { hugo } = conventions;
|
|
4170
4523
|
let data;
|
|
4171
4524
|
let body;
|
|
4172
4525
|
try {
|
|
@@ -4231,8 +4584,8 @@ function readFrontMatter(raw, file, hugo) {
|
|
|
4231
4584
|
if (!weight.success) throw new Error(`${file}: front matter 'weight' must be an int32`);
|
|
4232
4585
|
if (weight.data > 0) out.weight = weight.data;
|
|
4233
4586
|
}
|
|
4234
|
-
out.description = str("description");
|
|
4235
4587
|
}
|
|
4588
|
+
if (conventions.description) out.description = str("description");
|
|
4236
4589
|
for (const [key, value] of Object.entries(data)) {
|
|
4237
4590
|
if (RESERVED_KEYS.has(key) || value === void 0) continue;
|
|
4238
4591
|
out.meta[key] = value;
|
|
@@ -4261,7 +4614,7 @@ function topicIdFor(name, taken) {
|
|
|
4261
4614
|
taken.add(id);
|
|
4262
4615
|
return id;
|
|
4263
4616
|
}
|
|
4264
|
-
async function
|
|
4617
|
+
async function walkFiles(root, matches) {
|
|
4265
4618
|
const out = [];
|
|
4266
4619
|
const visit = async (dir) => {
|
|
4267
4620
|
const entries = (await readdir(dir, { withFileTypes: true })).sort(
|
|
@@ -4271,13 +4624,20 @@ async function walkMarkdownFiles(root) {
|
|
|
4271
4624
|
if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
|
|
4272
4625
|
const abs = join6(dir, entry.name);
|
|
4273
4626
|
if (entry.isDirectory()) await visit(abs);
|
|
4274
|
-
else if (entry.isFile() &&
|
|
4627
|
+
else if (entry.isFile() && matches(entry.name)) out.push(abs);
|
|
4275
4628
|
}
|
|
4276
4629
|
};
|
|
4277
4630
|
await visit(root);
|
|
4278
4631
|
return out;
|
|
4279
4632
|
}
|
|
4280
|
-
function
|
|
4633
|
+
function walkMarkdownFiles(root) {
|
|
4634
|
+
return walkFiles(root, (name) => /\.(md|markdown)$/i.test(name));
|
|
4635
|
+
}
|
|
4636
|
+
function warnCapped(warn, items, each, rest) {
|
|
4637
|
+
for (const item of items.slice(0, WARNING_EXAMPLES2)) warn(each(item));
|
|
4638
|
+
if (items.length > WARNING_EXAMPLES2) warn(rest(items.length - WARNING_EXAMPLES2));
|
|
4639
|
+
}
|
|
4640
|
+
function isRecord3(value) {
|
|
4281
4641
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
4282
4642
|
}
|
|
4283
4643
|
async function readTopicSidecar(dir) {
|
|
@@ -4286,7 +4646,7 @@ async function readTopicSidecar(dir) {
|
|
|
4286
4646
|
const raw = (await readFile3(path, "utf8")).replace(/^\uFEFF/, "");
|
|
4287
4647
|
const data = parseYaml(raw, { what: path });
|
|
4288
4648
|
if (data === null || data === void 0) return {};
|
|
4289
|
-
if (!
|
|
4649
|
+
if (!isRecord3(data)) throw new Error(`${path}: must be a mapping`);
|
|
4290
4650
|
const out = {};
|
|
4291
4651
|
if (typeof data.name === "string" && data.name.trim()) out.name = data.name.trim();
|
|
4292
4652
|
if (typeof data.description === "string" && data.description.trim()) {
|
|
@@ -4320,7 +4680,7 @@ async function readMkdocsDocsDir(mkdocsPath) {
|
|
|
4320
4680
|
tolerateUnknownTags: true,
|
|
4321
4681
|
maxAliasCount: 100
|
|
4322
4682
|
});
|
|
4323
|
-
const docsDir =
|
|
4683
|
+
const docsDir = isRecord3(config) && typeof config.docs_dir === "string" ? config.docs_dir : "docs";
|
|
4324
4684
|
return resolve4(dirname3(mkdocsPath), docsDir);
|
|
4325
4685
|
}
|
|
4326
4686
|
async function detectTableOfContents(rootDir, projectDir = rootDir) {
|
|
@@ -4335,6 +4695,10 @@ async function detectTableOfContents(rootDir, projectDir = rootDir) {
|
|
|
4335
4695
|
])
|
|
4336
4696
|
);
|
|
4337
4697
|
if (mkdocs) return { format: "mkdocs", path: mkdocs };
|
|
4698
|
+
const docfx = firstExisting(
|
|
4699
|
+
[DOCFX_JSON, "toc.yml", "TOC.yml", "toc.yaml"].map((name) => join6(rootDir, name))
|
|
4700
|
+
);
|
|
4701
|
+
if (docfx) return { format: "docfx" };
|
|
4338
4702
|
const files = await walkMarkdownFiles(rootDir);
|
|
4339
4703
|
if (files.some((file) => basename(file).replace(/\.(md|markdown)$/i, "") === HUGO_SECTION_PAGE)) {
|
|
4340
4704
|
return { format: "hugo" };
|
|
@@ -4354,6 +4718,7 @@ async function loadOutline(rootDir, toc, files) {
|
|
|
4354
4718
|
if (explicit && !existsSync(explicit)) {
|
|
4355
4719
|
throw new Error(`${toc.format} table of contents not found: ${explicit}`);
|
|
4356
4720
|
}
|
|
4721
|
+
if (toc.format === "docfx") return loadDocfxOutline(rootDir, explicit, files);
|
|
4357
4722
|
if (toc.format === "gitbook") {
|
|
4358
4723
|
const path2 = explicit ?? join6(rootDir, "SUMMARY.md");
|
|
4359
4724
|
const rel = insideRoot(rootDir, path2);
|
|
@@ -4396,16 +4761,68 @@ async function loadOutline(rootDir, toc, files) {
|
|
|
4396
4761
|
});
|
|
4397
4762
|
return { outline: parseJupyterBookToc(doc, tocDir, files, basename(path)), path };
|
|
4398
4763
|
}
|
|
4764
|
+
async function loadDocfxOutline(rootDir, explicit, files) {
|
|
4765
|
+
const configPath = join6(rootDir, DOCFX_JSON);
|
|
4766
|
+
let project;
|
|
4767
|
+
if (existsSync(configPath)) {
|
|
4768
|
+
let config;
|
|
4769
|
+
try {
|
|
4770
|
+
config = JSON.parse(await readOutlineText(configPath));
|
|
4771
|
+
} catch (error) {
|
|
4772
|
+
throw new Error(`${DOCFX_JSON}: ${error instanceof Error ? error.message : String(error)}`);
|
|
4773
|
+
}
|
|
4774
|
+
project = parseDocfxJson(config, DOCFX_JSON);
|
|
4775
|
+
}
|
|
4776
|
+
const entry = explicit === void 0 ? void 0 : insideRoot(rootDir, explicit);
|
|
4777
|
+
if (entry === null) {
|
|
4778
|
+
throw new Error(`${basename(explicit)} must live inside the content root ${rootDir}`);
|
|
4779
|
+
}
|
|
4780
|
+
const readToc = async (abs, rel) => parseYaml(await readOutlineText(abs), {
|
|
4781
|
+
what: rel,
|
|
4782
|
+
maxBytes: OUTLINE_MAX_BYTES,
|
|
4783
|
+
tolerateUnknownTags: true,
|
|
4784
|
+
maxAliasCount: 100
|
|
4785
|
+
});
|
|
4786
|
+
const tocs = /* @__PURE__ */ new Map();
|
|
4787
|
+
const warnings = [];
|
|
4788
|
+
for (const abs of await walkFiles(rootDir, (name) => /^toc\.ya?ml$/i.test(name))) {
|
|
4789
|
+
const rel = insideRoot(rootDir, abs);
|
|
4790
|
+
try {
|
|
4791
|
+
tocs.set(rel, await readToc(abs, rel));
|
|
4792
|
+
} catch (error) {
|
|
4793
|
+
if (rel === entry) throw error;
|
|
4794
|
+
warnings.push(`${rel}: ${error instanceof Error ? error.message : String(error)}; skipped`);
|
|
4795
|
+
}
|
|
4796
|
+
}
|
|
4797
|
+
if (entry !== void 0 && explicit !== void 0 && !tocs.has(entry)) {
|
|
4798
|
+
tocs.set(entry, await readToc(explicit, entry));
|
|
4799
|
+
}
|
|
4800
|
+
const publishes = project ? (file) => docfxPublishes(project, file) : void 0;
|
|
4801
|
+
const outline = parseDocfxToc({
|
|
4802
|
+
tocs,
|
|
4803
|
+
files: publishes ? files.filter(publishes) : files,
|
|
4804
|
+
...project ? { project } : {},
|
|
4805
|
+
...entry !== void 0 ? { entry } : {}
|
|
4806
|
+
});
|
|
4807
|
+
outline.warnings.unshift(...warnings);
|
|
4808
|
+
const path = outline.entry ? join6(rootDir, ...outline.entry.split("/")) : void 0;
|
|
4809
|
+
return {
|
|
4810
|
+
outline,
|
|
4811
|
+
...path ? { path } : project ? { path: configPath } : {},
|
|
4812
|
+
...publishes ? { publishes } : {}
|
|
4813
|
+
};
|
|
4814
|
+
}
|
|
4399
4815
|
var INLINE_LINK = /(!?)\[([^\]]*)\]\(\s*(<[^>]*>|[^)\s]+)((?:\s+"[^"]*")?)\s*\)/g;
|
|
4400
|
-
var
|
|
4816
|
+
var HAS_SCHEME3 = /^[a-z][a-z0-9+.-]*:/i;
|
|
4401
4817
|
function resolveInTree(ctx, target) {
|
|
4402
|
-
const
|
|
4403
|
-
|
|
4818
|
+
const fromRoot = ctx.tildeIsRoot && target.startsWith("~/");
|
|
4819
|
+
const resolved = posix3.normalize(fromRoot ? target.slice(2) : posix3.join(ctx.docDir, target));
|
|
4820
|
+
if (resolved === ".." || resolved.startsWith("../") || posix3.isAbsolute(resolved)) return null;
|
|
4404
4821
|
return resolved === "." ? "" : resolved;
|
|
4405
4822
|
}
|
|
4406
4823
|
function rewriteTarget(ctx, isImage, rawTarget) {
|
|
4407
4824
|
const target = rawTarget.startsWith("<") ? rawTarget.slice(1, -1) : rawTarget;
|
|
4408
|
-
if (target === "" ||
|
|
4825
|
+
if (target === "" || HAS_SCHEME3.test(target) || target.startsWith("//") || target.startsWith("#") || target.startsWith("/")) {
|
|
4409
4826
|
return null;
|
|
4410
4827
|
}
|
|
4411
4828
|
const hashAt = target.search(/[#?]/);
|
|
@@ -4479,11 +4896,18 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4479
4896
|
});
|
|
4480
4897
|
const toc = opts.toc ?? { format: "folders" };
|
|
4481
4898
|
const hugo = toc.format === "hugo";
|
|
4899
|
+
const docfx = toc.format === "docfx";
|
|
4900
|
+
const conventions = { hugo, description: hugo || docfx };
|
|
4482
4901
|
const ignore = new Set(opts.ignore ?? []);
|
|
4483
4902
|
const relOf = (abs) => relative3(rootDir, abs).split(sep).join("/");
|
|
4484
4903
|
let files = (await walkMarkdownFiles(rootDir)).filter((abs) => !ignore.has(relOf(abs)));
|
|
4485
|
-
const {
|
|
4904
|
+
const {
|
|
4905
|
+
outline,
|
|
4906
|
+
path: outlinePath,
|
|
4907
|
+
publishes
|
|
4908
|
+
} = await loadOutline(rootDir, toc, files.map(relOf));
|
|
4486
4909
|
for (const message of outline?.warnings ?? []) warn(message);
|
|
4910
|
+
if (publishes) files = files.filter((abs) => publishes(relOf(abs)));
|
|
4487
4911
|
if (outline) {
|
|
4488
4912
|
const consumed = new Set(outline.consumed.map((file) => file.normalize("NFC")));
|
|
4489
4913
|
files = files.filter((abs) => !consumed.has(relOf(abs).normalize("NFC")));
|
|
@@ -4531,29 +4955,33 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4531
4955
|
};
|
|
4532
4956
|
const placements = /* @__PURE__ */ new Map();
|
|
4533
4957
|
if (outline) {
|
|
4958
|
+
const duplicates = [];
|
|
4534
4959
|
const walk = (topic, chain) => {
|
|
4535
4960
|
for (const entry of topic.entries) {
|
|
4536
4961
|
const key = entry.file.normalize("NFC");
|
|
4537
|
-
if (placements.has(key))
|
|
4538
|
-
|
|
4539
|
-
`${entry.file}: listed more than once in the table of contents; the first place wins`
|
|
4540
|
-
);
|
|
4541
|
-
} else {
|
|
4542
|
-
placements.set(key, { chain, entry });
|
|
4543
|
-
}
|
|
4962
|
+
if (placements.has(key)) duplicates.push(entry.file);
|
|
4963
|
+
else placements.set(key, { chain, entry });
|
|
4544
4964
|
}
|
|
4545
4965
|
for (const child of topic.children) walk(child, [...chain, child]);
|
|
4546
4966
|
};
|
|
4547
4967
|
walk(outline.root, []);
|
|
4968
|
+
warnCapped(
|
|
4969
|
+
warn,
|
|
4970
|
+
duplicates,
|
|
4971
|
+
(file) => `${file}: listed more than once in the table of contents; the first place wins`,
|
|
4972
|
+
(more) => `${more} more files are listed more than once in the table of contents`
|
|
4973
|
+
);
|
|
4548
4974
|
}
|
|
4549
4975
|
const outlineTopicIds = /* @__PURE__ */ new Map();
|
|
4976
|
+
let outlineTooDeep = false;
|
|
4550
4977
|
const ensureOutlineChain = (chain) => {
|
|
4551
4978
|
if (chain.length === 0) {
|
|
4552
4979
|
rootTopicUsed = true;
|
|
4553
4980
|
return [rootTopicId];
|
|
4554
4981
|
}
|
|
4982
|
+
if (chain.length > MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1) outlineTooDeep = true;
|
|
4555
4983
|
const ids = [];
|
|
4556
|
-
for (const node of chain) {
|
|
4984
|
+
for (const node of chain.slice(0, MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1)) {
|
|
4557
4985
|
let id = outlineTopicIds.get(node);
|
|
4558
4986
|
if (!id) {
|
|
4559
4987
|
id = topicIdFor(node.name, takenTopicIds);
|
|
@@ -4594,12 +5022,13 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4594
5022
|
const fileById = /* @__PURE__ */ new Map();
|
|
4595
5023
|
const idByRel = /* @__PURE__ */ new Map();
|
|
4596
5024
|
const seenRel = /* @__PURE__ */ new Set();
|
|
5025
|
+
const unlisted = [];
|
|
4597
5026
|
for (const abs of files) {
|
|
4598
5027
|
const rel = relOf(abs);
|
|
4599
5028
|
const relDir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
|
|
4600
5029
|
const relNoExt = rel.replace(/\.(md|markdown)$/i, "").normalize("NFC");
|
|
4601
5030
|
const raw = (await readFile3(abs, "utf8")).replace(/^\uFEFF/, "");
|
|
4602
|
-
const fm = readFrontMatter(raw, rel,
|
|
5031
|
+
const fm = readFrontMatter(raw, rel, conventions);
|
|
4603
5032
|
if (fm.unpublished) {
|
|
4604
5033
|
warn(`${rel}: skipped, ${fm.unpublished} page`);
|
|
4605
5034
|
continue;
|
|
@@ -4613,7 +5042,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4613
5042
|
fileById.set(id, rel);
|
|
4614
5043
|
idByRel.set(relNoExt, id);
|
|
4615
5044
|
const stem2 = rel.slice(rel.lastIndexOf("/") + 1).replace(/\.(md|markdown)$/i, "");
|
|
4616
|
-
let title = fm.title ?? firstHeading(fm.body) ?? stem2;
|
|
5045
|
+
let title = docfx ? firstHeading(fm.body) ?? fm.title ?? stem2 : fm.title ?? firstHeading(fm.body) ?? stem2;
|
|
4617
5046
|
let ordinal = fm.order;
|
|
4618
5047
|
let topicPath;
|
|
4619
5048
|
const placement = placements.get(rel.normalize("NFC"));
|
|
@@ -4622,8 +5051,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4622
5051
|
if (placement.entry.title) title = placement.entry.title;
|
|
4623
5052
|
if (placement.entry.order !== void 0) ordinal = placement.entry.order;
|
|
4624
5053
|
} else {
|
|
4625
|
-
if (outline)
|
|
4626
|
-
warn(`${rel}: not in the ${outline.format} table of contents; filed under its folder`);
|
|
5054
|
+
if (outline) unlisted.push(rel);
|
|
4627
5055
|
topicPath = await ensureTopicChain(relDir);
|
|
4628
5056
|
if (hugo && ordinal === void 0) ordinal = fm.weight;
|
|
4629
5057
|
}
|
|
@@ -4647,7 +5075,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4647
5075
|
const parentId = topicPath[topicPath.length - 1];
|
|
4648
5076
|
topicPath = [...topicPath, ensureShelf(parentId, fm.subcategory, rel)];
|
|
4649
5077
|
}
|
|
4650
|
-
const summary = fm.summary ??
|
|
5078
|
+
const summary = fm.summary ?? fm.description ?? firstParagraph(fm.body);
|
|
4651
5079
|
loaded.push({
|
|
4652
5080
|
rel,
|
|
4653
5081
|
file: rel,
|
|
@@ -4679,12 +5107,22 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4679
5107
|
}
|
|
4680
5108
|
};
|
|
4681
5109
|
nameFromPages(outline.root);
|
|
4682
|
-
|
|
4683
|
-
|
|
4684
|
-
|
|
4685
|
-
|
|
4686
|
-
|
|
4687
|
-
|
|
5110
|
+
warnCapped(
|
|
5111
|
+
warn,
|
|
5112
|
+
unlisted,
|
|
5113
|
+
(file) => `${file}: not in the ${outline.format} table of contents; filed under its folder`,
|
|
5114
|
+
(more) => `${more} more files are not in the ${outline.format} table of contents; filed under their folders`
|
|
5115
|
+
);
|
|
5116
|
+
warnCapped(
|
|
5117
|
+
warn,
|
|
5118
|
+
[...placements].filter(([file]) => !seenRel.has(file)).map(([, p]) => p.entry.file),
|
|
5119
|
+
(file) => `${file}: named by the table of contents but not found among the Markdown files`,
|
|
5120
|
+
(more) => `${more} more files named by the table of contents are not among the Markdown files`
|
|
5121
|
+
);
|
|
5122
|
+
if (outlineTooDeep) {
|
|
5123
|
+
warn(
|
|
5124
|
+
`the table of contents nests deeper than ${MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1} levels; deeper sections are folded into their ancestors`
|
|
5125
|
+
);
|
|
4688
5126
|
}
|
|
4689
5127
|
}
|
|
4690
5128
|
if (rootTopicUsed) {
|
|
@@ -4702,6 +5140,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4702
5140
|
}
|
|
4703
5141
|
const assets = /* @__PURE__ */ new Map();
|
|
4704
5142
|
const documents = [];
|
|
5143
|
+
const linkWarnings = [];
|
|
4705
5144
|
for (const entry of loaded) {
|
|
4706
5145
|
const ctx = {
|
|
4707
5146
|
rootDir,
|
|
@@ -4710,8 +5149,11 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4710
5149
|
idByRel,
|
|
4711
5150
|
uri: opts.uri,
|
|
4712
5151
|
assets,
|
|
4713
|
-
|
|
4714
|
-
|
|
5152
|
+
// A docfx docset draws on dependent repositories (`~/reusable-content`)
|
|
5153
|
+
// that a checkout never holds, so a missing image is expected there.
|
|
5154
|
+
missingAssets: opts.missingAssets ?? (docfx ? "warn" : "error"),
|
|
5155
|
+
tildeIsRoot: docfx,
|
|
5156
|
+
warn: (message) => linkWarnings.push(message)
|
|
4715
5157
|
};
|
|
4716
5158
|
documents.push(
|
|
4717
5159
|
CatalogDocumentSchema.parse({
|
|
@@ -4720,6 +5162,12 @@ async function loadMarkdownCatalog(rootDir, opts) {
|
|
|
4720
5162
|
})
|
|
4721
5163
|
);
|
|
4722
5164
|
}
|
|
5165
|
+
warnCapped(
|
|
5166
|
+
warn,
|
|
5167
|
+
linkWarnings,
|
|
5168
|
+
(message) => message,
|
|
5169
|
+
(more) => `${more} more link and image warnings`
|
|
5170
|
+
);
|
|
4723
5171
|
return {
|
|
4724
5172
|
topics,
|
|
4725
5173
|
documents,
|
package/package.json
CHANGED