@docusaurus/utils 2.0.0-beta.fc64c12e4 → 2.0.0

package/lib/markdownLinks.d.ts

@@ -4,24 +4,68 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Content plugins have a base path and a localized path to source content from.
+ * We will look into the localized path in priority.
+ */
 export declare type ContentPaths = {
+    /**
+     * The absolute path to the base content directory, like `"<siteDir>/docs"`.
+     */
     contentPath: string;
+    /**
+     * The absolute path to the localized content directory, like
+     * `"<siteDir>/i18n/zh-Hans/plugin-content-docs"`.
+     */
     contentPathLocalized: string;
 };
+/** Data structure representing each broken Markdown link to be reported. */
 export declare type BrokenMarkdownLink<T extends ContentPaths> = {
+    /** Absolute path to the file containing this link. */
     filePath: string;
+    /**
+     * This is generic because it may contain extra metadata like version name,
+     * which the reporter can provide for context.
+     */
     contentPaths: T;
+    /**
+     * The content of the link, like `"./brokenFile.md"`
+     */
     link: string;
 };
-export declare type ReplaceMarkdownLinksParams<T extends ContentPaths> = {
+/**
+ * Takes a Markdown file and replaces relative file references with their URL
+ * counterparts, e.g. `[link](./intro.md)` => `[link](/docs/intro)`, preserving
+ * everything else.
+ *
+ * This method uses best effort to find a matching file. The file reference can
+ * be relative to the directory of the current file (most likely) or any of the
+ * content paths (so `/tutorials/intro.md` can be resolved as
+ * `<siteDir>/docs/tutorials/intro.md`). Links that contain the `http(s):` or
+ * `@site/` prefix will always be ignored.
+ */
+export declare function replaceMarkdownLinks<T extends ContentPaths>({ siteDir, fileString, filePath, contentPaths, sourceToPermalink, }: {
+    /** Absolute path to the site directory, used to resolve aliased paths. */
     siteDir: string;
+    /** The Markdown file content to be processed. */
     fileString: string;
+    /** Absolute path to the current file containing `fileString`. */
     filePath: string;
+    /** The content paths which the file reference may live in. */
     contentPaths: T;
-    sourceToPermalink: Record<string, string>;
-};
-export declare type ReplaceMarkdownLinksReturn<T extends ContentPaths> = {
+    /**
+     * A map from source paths to their URLs. Source paths are `@site` aliased.
+     */
+    sourceToPermalink: {
+        [aliasedPath: string]: string;
+    };
+}): {
+    /**
+     * The content with all Markdown file references replaced with their URLs.
+     * Unresolved links are left as-is.
+     */
     newContent: string;
+    /** The list of broken links,  */
     brokenMarkdownLinks: BrokenMarkdownLink<T>[];
 };
-export declare function replaceMarkdownLinks<T extends ContentPaths>({ siteDir, fileString, filePath, contentPaths, sourceToPermalink, }: ReplaceMarkdownLinksParams<T>): ReplaceMarkdownLinksReturn<T>;
+//# sourceMappingURL=markdownLinks.d.ts.map

package/lib/markdownLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownLinks.d.ts","sourceRoot":"","sources":["../src/markdownLinks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;GAGG;AACH,oBAAY,YAAY,GAAG;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,4EAA4E;AAC5E,oBAAY,kBAAkB,CAAC,CAAC,SAAS,YAAY,IAAI;IACvD,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,CAAC,CAAC;IAChB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,YAAY,EAAE,EAC3D,OAAO,EACP,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,iBAAiB,GAClB,EAAE;IACD,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,YAAY,EAAE,CAAC,CAAC;IAChB;;OAEG;IACH,iBAAiB,EAAE;QAAC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;KAAC,CAAC;CACpD,GAAG;IACF;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;CAC9C,CAmFA"}

package/lib/markdownLinks.js

@@ -7,35 +7,78 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.replaceMarkdownLinks = void 0;
-const url_1 = require("url");
-const index_1 = require("./index");
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const dataFileUtils_1 = require("./dataFileUtils");
+const pathUtils_1 = require("./pathUtils");
+/**
+ * Takes a Markdown file and replaces relative file references with their URL
+ * counterparts, e.g. `[link](./intro.md)` => `[link](/docs/intro)`, preserving
+ * everything else.
+ *
+ * This method uses best effort to find a matching file. The file reference can
+ * be relative to the directory of the current file (most likely) or any of the
+ * content paths (so `/tutorials/intro.md` can be resolved as
+ * `<siteDir>/docs/tutorials/intro.md`). Links that contain the `http(s):` or
+ * `@site/` prefix will always be ignored.
+ */
 function replaceMarkdownLinks({ siteDir, fileString, filePath, contentPaths, sourceToPermalink, }) {
-    const { contentPath, contentPathLocalized } = contentPaths;
     const brokenMarkdownLinks = [];
     // Replace internal markdown linking (except in fenced blocks).
     let fencedBlock = false;
+    let lastCodeFence = '';
     const lines = fileString.split('\n').map((line) => {
         if (line.trim().startsWith('```')) {
-            fencedBlock = !fencedBlock;
+            const codeFence = line.trim().match(/^`+/)[0];
+            if (!fencedBlock) {
+                fencedBlock = true;
+                lastCodeFence = codeFence;
+                // If we are in a ````-fenced block, all ``` would be plain text instead
+                // of fences
+            }
+            else if (codeFence.length >= lastCodeFence.length) {
+                fencedBlock = false;
+            }
         }
         if (fencedBlock) {
             return line;
         }
         let modifiedLine = line;
         // Replace inline-style links or reference-style links e.g:
-        // This is [Document 1](doc1.md) -> we replace this doc1.md with correct link
-        // [doc1]: doc1.md -> we replace this doc1.md with correct link
-        const mdRegex = /(?:(?:\]\()|(?:\]:\s?))(?!https)([^'")\]\s>]+\.mdx?)/g;
+        // This is [Document 1](doc1.md)
+        // [doc1]: doc1.md
+        const mdRegex = /(?:\]\(|\]:\s*)(?!https?:\/\/|@site\/)(?<filename>[^'")\]\s>]+\.mdx?)/g;
         let mdMatch = mdRegex.exec(modifiedLine);
         while (mdMatch !== null) {
             // Replace it to correct html link.
-            const mdLink = mdMatch[1];
-            const aliasedSource = (source) => index_1.aliasedSitePath(source, siteDir);
-            const permalink = sourceToPermalink[aliasedSource(url_1.resolve(filePath, mdLink))] ||
-                sourceToPermalink[aliasedSource(`${contentPathLocalized}/${mdLink}`)] ||
-                sourceToPermalink[aliasedSource(`${contentPath}/${mdLink}`)];
+            const mdLink = mdMatch.groups.filename;
+            const sourcesToTry = [];
+            // ./file.md and ../file.md are always relative to the current file
+            if (!mdLink.startsWith('./') && !mdLink.startsWith('../')) {
+                sourcesToTry.push(...(0, dataFileUtils_1.getContentPathList)(contentPaths), siteDir);
+            }
+            // /file.md is always relative to the content path
+            if (!mdLink.startsWith('/')) {
+                sourcesToTry.push(path_1.default.dirname(filePath));
+            }
+            const aliasedSourceMatch = sourcesToTry
+                .map((p) => path_1.default.join(p, decodeURIComponent(mdLink)))
+                .map((source) => (0, pathUtils_1.aliasedSitePath)(source, siteDir))
+                .find((source) => sourceToPermalink[source]);
+            const permalink = aliasedSourceMatch
+                ? sourceToPermalink[aliasedSourceMatch]
+                : undefined;
             if (permalink) {
-                modifiedLine = modifiedLine.replace(mdLink, permalink);
+                // MDX won't be happy if the permalink contains a space, we need to
+                // convert it to %20
+                const encodedPermalink = permalink
+                    .split('/')
+                    .map((part) => part.replace(/\s/g, '%20'))
+                    .join('/');
+                modifiedLine = modifiedLine.replace(mdMatch[0], mdMatch[0].replace(mdLink, encodedPermalink));
+                // Adjust the lastIndex to avoid passing over the next link if the
+                // newly replaced URL is shorter.
+                mdRegex.lastIndex += encodedPermalink.length - mdLink.length;
             }
             else {
                 const brokenMarkdownLink = {
@@ -53,3 +96,4 @@ function replaceMarkdownLinks({ siteDir, fileString, filePath, contentPaths, sou
     return { newContent, brokenMarkdownLinks };
 }
 exports.replaceMarkdownLinks = replaceMarkdownLinks;
+//# sourceMappingURL=markdownLinks.js.map

package/lib/markdownLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownLinks.js","sourceRoot":"","sources":["../src/markdownLinks.ts"],"names":[],"mappings":"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"}

package/lib/markdownUtils.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type SluggerOptions } from './slugger';
+/**
+ * Parses custom ID from a heading. The ID can contain any characters except
+ * `{#` and `}`.
+ *
+ * @param heading e.g. `## Some heading {#some-heading}` where the last
+ * character must be `}` for the ID to be recognized
+ */
+export declare function parseMarkdownHeadingId(heading: string): {
+    /**
+     * The heading content sans the ID part, right-trimmed. e.g. `## Some heading`
+     */
+    text: string;
+    /** The heading ID. e.g. `some-heading` */
+    id: string | undefined;
+};
+/**
+ * Creates an excerpt of a Markdown file. This function will:
+ *
+ * - Ignore h1 headings (setext or atx)
+ * - Ignore import/export
+ * - Ignore code blocks
+ *
+ * And for the first contentful line, it will strip away most Markdown
+ * syntax, including HTML tags, emphasis, links (keeping the text), etc.
+ */
+export declare function createExcerpt(fileString: string): string | undefined;
+/**
+ * Takes a raw Markdown file content, and parses the front matter using
+ * gray-matter. Worth noting that gray-matter accepts TOML and other markup
+ * languages as well.
+ *
+ * @throws Throws when gray-matter throws. e.g.:
+ * ```md
+ * ---
+ * foo: : bar
+ * ---
+ * ```
+ */
+export declare function parseFrontMatter(markdownFileContent: string): {
+    /** Front matter as parsed by gray-matter. */
+    frontMatter: {
+        [key: string]: unknown;
+    };
+    /** The remaining content, trimmed. */
+    content: string;
+};
+declare type ParseMarkdownContentTitleOptions = {
+    /**
+     * If `true`, the matching title will be removed from the returned content.
+     * We can promise that at least one empty line will be left between the
+     * content before and after, but you shouldn't make too much assumption
+     * about what's left.
+     */
+    removeContentTitle?: boolean;
+};
+/**
+ * Takes the raw Markdown content, without front matter, and tries to find an h1
+ * title (setext or atx) to be used as metadata.
+ *
+ * It only searches until the first contentful paragraph, ignoring import/export
+ * declarations.
+ *
+ * It will try to convert markdown to reasonable text, but won't be best effort,
+ * since it's only used as a fallback when `frontMatter.title` is not provided.
+ * For now, we just unwrap inline code (``# `config.js` `` => `config.js`).
+ */
+export declare function parseMarkdownContentTitle(contentUntrimmed: string, options?: ParseMarkdownContentTitleOptions): {
+    /** The content, optionally without the content title. */
+    content: string;
+    /** The title, trimmed and without the `#`. */
+    contentTitle: string | undefined;
+};
+/**
+ * Makes a full-round parse.
+ *
+ * @throws Throws when `parseFrontMatter` throws, usually because of invalid
+ * syntax.
+ */
+export declare function parseMarkdownString(markdownFileContent: string, options?: ParseMarkdownContentTitleOptions): {
+    /** @see {@link parseFrontMatter} */
+    frontMatter: {
+        [key: string]: unknown;
+    };
+    /** @see {@link parseMarkdownContentTitle} */
+    contentTitle: string | undefined;
+    /** @see {@link createExcerpt} */
+    excerpt: string | undefined;
+    /**
+     * Content without front matter and (optionally) without title, depending on
+     * the `removeContentTitle` option.
+     */
+    content: string;
+};
+export declare type WriteHeadingIDOptions = SluggerOptions & {
+    /** Overwrite existing heading IDs. */
+    overwrite?: boolean;
+};
+/**
+ * Takes Markdown content, returns new content with heading IDs written.
+ * Respects existing IDs (unless `overwrite=true`) and never generates colliding
+ * IDs (through the slugger).
+ */
+export declare function writeMarkdownHeadingId(content: string, options?: WriteHeadingIDOptions): string;
+export {};
+//# sourceMappingURL=markdownUtils.d.ts.map

package/lib/markdownUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownUtils.d.ts","sourceRoot":"","sources":["../src/markdownUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,WAAW,CAAC;AAM3E;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG;IACvD;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACxB,CAUA;AAID;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA4EpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,mBAAmB,EAAE,MAAM,GAAG;IAC7D,6CAA6C;IAC7C,WAAW,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAC,CAAC;IACtC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB,CAMA;AASD,aAAK,gCAAgC,GAAG;IACtC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,gCAAgC,GACzC;IACD,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAyCA;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,mBAAmB,EAAE,MAAM,EAC3B,OAAO,CAAC,EAAE,gCAAgC,GACzC;IACD,oCAAoC;IACpC,WAAW,EAAE;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAC,CAAC;IACtC,6CAA6C;IAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iCAAiC;IACjC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAuBA;AA4BD,oBAAY,qBAAqB,GAAG,cAAc,GAAG;IACnD,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,qBAA+D,GACvE,MAAM,CAoCR"}

package/lib/markdownUtils.js

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeMarkdownHeadingId = exports.parseMarkdownString = exports.parseMarkdownContentTitle = exports.parseFrontMatter = exports.createExcerpt = exports.parseMarkdownHeadingId = void 0;
+const tslib_1 = require("tslib");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const gray_matter_1 = tslib_1.__importDefault(require("gray-matter"));
+const slugger_1 = require("./slugger");
+// Some utilities for parsing Markdown content. These things are only used on
+// server-side when we infer metadata like `title` and `description` from the
+// content. Most parsing is still done in MDX through the mdx-loader.
+/**
+ * Parses custom ID from a heading. The ID can contain any characters except
+ * `{#` and `}`.
+ *
+ * @param heading e.g. `## Some heading {#some-heading}` where the last
+ * character must be `}` for the ID to be recognized
+ */
+function parseMarkdownHeadingId(heading) {
+    const customHeadingIdRegex = /\s*\{#(?<id>(?:.(?!\{#|\}))*.)\}$/;
+    const matches = customHeadingIdRegex.exec(heading);
+    if (matches) {
+        return {
+            text: heading.replace(matches[0], ''),
+            id: matches.groups.id,
+        };
+    }
+    return { text: heading, id: undefined };
+}
+exports.parseMarkdownHeadingId = parseMarkdownHeadingId;
+// TODO: Find a better way to do so, possibly by compiling the Markdown content,
+// stripping out HTML tags and obtaining the first line.
+/**
+ * Creates an excerpt of a Markdown file. This function will:
+ *
+ * - Ignore h1 headings (setext or atx)
+ * - Ignore import/export
+ * - Ignore code blocks
+ *
+ * And for the first contentful line, it will strip away most Markdown
+ * syntax, including HTML tags, emphasis, links (keeping the text), etc.
+ */
+function createExcerpt(fileString) {
+    const fileLines = fileString
+        .trimStart()
+        // Remove Markdown alternate title
+        .replace(/^[^\n]*\n[=]+/g, '')
+        .split('\n');
+    let inCode = false;
+    let inImport = false;
+    let lastCodeFence = '';
+    for (const fileLine of fileLines) {
+        if (fileLine === '' && inImport) {
+            inImport = false;
+        }
+        // Skip empty line.
+        if (!fileLine.trim()) {
+            continue;
+        }
+        // Skip import/export declaration.
+        if ((/^(?:import|export)\s.*/.test(fileLine) || inImport) && !inCode) {
+            inImport = true;
+            continue;
+        }
+        // Skip code block line.
+        if (fileLine.trim().startsWith('```')) {
+            const codeFence = fileLine.trim().match(/^`+/)[0];
+            if (!inCode) {
+                inCode = true;
+                lastCodeFence = codeFence;
+                // If we are in a ````-fenced block, all ``` would be plain text instead
+                // of fences
+            }
+            else if (codeFence.length >= lastCodeFence.length) {
+                inCode = false;
+            }
+            continue;
+        }
+        else if (inCode) {
+            continue;
+        }
+        const cleanedLine = fileLine
+            // Remove HTML tags.
+            .replace(/<[^>]*>/g, '')
+            // Remove Title headers
+            .replace(/^#[^#]+#?/gm, '')
+            // Remove Markdown + ATX-style headers
+            .replace(/^#{1,6}\s*(?<text>[^#]*)\s*#{0,6}/gm, '$1')
+            // Remove emphasis.
+            .replace(/(?<opening>[*_]{1,3})(?<text>.*?)\1/g, '$2')
+            // Remove strikethroughs.
+            .replace(/~~(?<text>\S.*\S)~~/g, '$1')
+            // Remove images.
+            .replace(/!\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
+            // Remove footnotes.
+            .replace(/\[\^.+?\](?:: .*$)?/g, '')
+            // Remove inline links.
+            .replace(/\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
+            // Remove inline code.
+            .replace(/`(?<text>.+?)`/g, '$1')
+            // Remove blockquotes.
+            .replace(/^\s{0,3}>\s?/g, '')
+            // Remove admonition definition.
+            .replace(/:::.*/, '')
+            // Remove Emoji names within colons include preceding whitespace.
+            .replace(/\s?:(?:::|[^:\n])+:/g, '')
+            // Remove custom Markdown heading id.
+            .replace(/\{#*[\w-]+\}/, '')
+            .trim();
+        if (cleanedLine) {
+            return cleanedLine;
+        }
+    }
+    return undefined;
+}
+exports.createExcerpt = createExcerpt;
+/**
+ * Takes a raw Markdown file content, and parses the front matter using
+ * gray-matter. Worth noting that gray-matter accepts TOML and other markup
+ * languages as well.
+ *
+ * @throws Throws when gray-matter throws. e.g.:
+ * ```md
+ * ---
+ * foo: : bar
+ * ---
+ * ```
+ */
+function parseFrontMatter(markdownFileContent) {
+    const { data, content } = (0, gray_matter_1.default)(markdownFileContent);
+    return {
+        frontMatter: data,
+        content: content.trim(),
+    };
+}
+exports.parseFrontMatter = parseFrontMatter;
+function toTextContentTitle(contentTitle) {
+    if (contentTitle.startsWith('`') && contentTitle.endsWith('`')) {
+        return contentTitle.substring(1, contentTitle.length - 1);
+    }
+    return contentTitle;
+}
+/**
+ * Takes the raw Markdown content, without front matter, and tries to find an h1
+ * title (setext or atx) to be used as metadata.
+ *
+ * It only searches until the first contentful paragraph, ignoring import/export
+ * declarations.
+ *
+ * It will try to convert markdown to reasonable text, but won't be best effort,
+ * since it's only used as a fallback when `frontMatter.title` is not provided.
+ * For now, we just unwrap inline code (``# `config.js` `` => `config.js`).
+ */
+function parseMarkdownContentTitle(contentUntrimmed, options) {
+    const removeContentTitleOption = options?.removeContentTitle ?? false;
+    const content = contentUntrimmed.trim();
+    // We only need to detect import statements that will be parsed by MDX as
+    // `import` nodes, as broken syntax can't render anyways. That means any block
+    // that has `import` at the very beginning and surrounded by empty lines.
+    const contentWithoutImport = content
+        .replace(/^(?:import\s(?:.|\r?\n(?!\r?\n))*(?:\r?\n){2,})*/, '')
+        .trim();
+    const regularTitleMatch = /^#[ \t]+(?<title>[^ \t].*)(?:\r?\n|$)/.exec(contentWithoutImport);
+    const alternateTitleMatch = /^(?<title>.*)\r?\n=+(?:\r?\n|$)/.exec(contentWithoutImport);
+    const titleMatch = regularTitleMatch ?? alternateTitleMatch;
+    if (!titleMatch) {
+        return { content, contentTitle: undefined };
+    }
+    const newContent = removeContentTitleOption
+        ? content.replace(titleMatch[0], '')
+        : content;
+    if (regularTitleMatch) {
+        return {
+            content: newContent.trim(),
+            contentTitle: toTextContentTitle(regularTitleMatch
+                .groups.title.trim()
+                .replace(/\s*(?:\{#*[\w-]+\}|#+)$/, '')).trim(),
+        };
+    }
+    return {
+        content: newContent.trim(),
+        contentTitle: toTextContentTitle(alternateTitleMatch.groups.title.trim().replace(/\s*=+$/, '')).trim(),
+    };
+}
+exports.parseMarkdownContentTitle = parseMarkdownContentTitle;
+/**
+ * Makes a full-round parse.
+ *
+ * @throws Throws when `parseFrontMatter` throws, usually because of invalid
+ * syntax.
+ */
+function parseMarkdownString(markdownFileContent, options) {
+    try {
+        const { frontMatter, content: contentWithoutFrontMatter } = parseFrontMatter(markdownFileContent);
+        const { content, contentTitle } = parseMarkdownContentTitle(contentWithoutFrontMatter, options);
+        const excerpt = createExcerpt(content);
+        return {
+            frontMatter,
+            content,
+            contentTitle,
+            excerpt,
+        };
+    }
+    catch (err) {
+        logger_1.default.error(`Error while parsing Markdown front matter.
+This can happen if you use special characters in front matter values (try using double quotes around that value).`);
+        throw err;
+    }
+}
+exports.parseMarkdownString = parseMarkdownString;
+function unwrapMarkdownLinks(line) {
+    return line.replace(/\[(?<alt>[^\]]+)\]\([^)]+\)/g, (match, p1) => p1);
+}
+function addHeadingId(line, slugger, maintainCase) {
+    let headingLevel = 0;
+    while (line.charAt(headingLevel) === '#') {
+        headingLevel += 1;
+    }
+    const headingText = line.slice(headingLevel).trimEnd();
+    const headingHashes = line.slice(0, headingLevel);
+    const slug = slugger.slug(unwrapMarkdownLinks(headingText).trim(), {
+        maintainCase,
+    });
+    return `${headingHashes}${headingText} {#${slug}}`;
+}
+/**
+ * Takes Markdown content, returns new content with heading IDs written.
+ * Respects existing IDs (unless `overwrite=true`) and never generates colliding
+ * IDs (through the slugger).
+ */
+function writeMarkdownHeadingId(content, options = { maintainCase: false, overwrite: false }) {
+    const { maintainCase = false, overwrite = false } = options;
+    const lines = content.split('\n');
+    const slugger = (0, slugger_1.createSlugger)();
+    // If we can't overwrite existing slugs, make sure other headings don't
+    // generate colliding slugs by first marking these slugs as occupied
+    if (!overwrite) {
+        lines.forEach((line) => {
+            const parsedHeading = parseMarkdownHeadingId(line);
+            if (parsedHeading.id) {
+                slugger.slug(parsedHeading.id);
+            }
+        });
+    }
+    let inCode = false;
+    return lines
+        .map((line) => {
+        if (line.startsWith('```')) {
+            inCode = !inCode;
+            return line;
+        }
+        // Ignore h1 headings, as we don't create anchor links for those
+        if (inCode || !line.startsWith('##')) {
+            return line;
+        }
+        const parsedHeading = parseMarkdownHeadingId(line);
+        // Do not process if id is already there
+        if (parsedHeading.id && !overwrite) {
+            return line;
+        }
+        return addHeadingId(parsedHeading.text, slugger, maintainCase);
+    })
+        .join('\n');
+}
+exports.writeMarkdownHeadingId = writeMarkdownHeadingId;
+//# sourceMappingURL=markdownUtils.js.map

package/lib/markdownUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownUtils.js","sourceRoot":"","sources":["../src/markdownUtils.ts"],"names":[],"mappings":"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"}

package/lib/pathUtils.d.ts

@@ -5,4 +5,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 export declare const isNameTooLong: (str: string) => boolean;
-export declare const shortName: (str: string) => string;
+export declare function shortName(str: string): string;
+/**
+ * Convert Windows backslash paths to posix style paths.
+ * E.g: endi\lie -> endi/lie
+ *
+ * Returns original path if the posix counterpart is not valid Windows path.
+ * This makes the legacy code that uses posixPath safe; but also makes it less
+ * useful when you actually want a path with forward slashes (e.g. for URL)
+ *
+ * Adopted from https://github.com/sindresorhus/slash/blob/main/index.js
+ */
+export declare function posixPath(str: string): string;
+/**
+ * When you want to display a path in a message/warning/error, it's more
+ * convenient to:
+ *
+ * - make it relative to `cwd()`
+ * - convert to posix (ie not using windows \ path separator)
+ *
+ * This way, Jest tests can run more reliably on any computer/CI on both
+ * Unix/Windows
+ * For Windows users this is not perfect (as they see / instead of \) but it's
+ * probably good enough
+ */
+export declare function toMessageRelativeFilePath(filePath: string): string;
+/**
+ * Alias filepath relative to site directory, very useful so that we
+ * don't expose user's site structure.
+ * Example: some/path/to/website/docs/foo.md -> @site/docs/foo.md
+ */
+export declare function aliasedSitePath(filePath: string, siteDir: string): string;
+/**
+ * When you have a path like C:\X\Y
+ * It is not safe to use directly when generating code
+ * For example, this would fail due to unescaped \:
+ * `<img src={require('${filePath}')} />`
+ * But this would work: `<img src={require('${escapePath(filePath)}')} />`
+ *
+ * posixPath can't be used in all cases, because forward slashes are only valid
+ * Windows paths when they don't contain non-ascii characters, and posixPath
+ * doesn't escape those that fail to be converted.
+ */
+export declare function escapePath(str: string): string;
+export declare function addTrailingPathSeparator(str: string): string;
+//# sourceMappingURL=pathUtils.d.ts.map

package/lib/pathUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,eAAO,MAAM,aAAa,QAAS,MAAM,KAAG,OAMgC,CAAC;AAE7E,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiB7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAY7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK5D"}