@docusaurus/utils 2.0.0-beta.15d451942 → 2.0.0-beta.18

package/lib/jsUtils.js

@@ -0,0 +1,94 @@
+"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.reportMessage = exports.findAsyncSequential = exports.mapAsyncSequential = exports.removePrefix = exports.removeSuffix = void 0;
+const tslib_1 = require("tslib");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+/** Removes a given string suffix from `str`. */
+function removeSuffix(str, suffix) {
+    if (suffix === '') {
+        // str.slice(0, 0) is ""
+        return str;
+    }
+    return str.endsWith(suffix) ? str.slice(0, -suffix.length) : str;
+}
+exports.removeSuffix = removeSuffix;
+/** Removes a given string prefix from `str`. */
+function removePrefix(str, prefix) {
+    return str.startsWith(prefix) ? str.slice(prefix.length) : str;
+}
+exports.removePrefix = removePrefix;
+/**
+ * `Array#map` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param action An async action to be performed on every array item. Will be
+ * awaited before working on the next.
+ * @returns The list of results returned from every `action(item)`
+ */
+async function mapAsyncSequential(array, action) {
+    const results = [];
+    for (const t of array) {
+        const result = await action(t);
+        results.push(result);
+    }
+    return results;
+}
+exports.mapAsyncSequential = mapAsyncSequential;
+/**
+ * `Array#find` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param predicate An async predicate to be called on every array item. Should
+ * return a boolean indicating whether the currently element should be returned.
+ * @returns The function immediately returns the first item on which `predicate`
+ * returns `true`, or `undefined` if none matches the predicate.
+ */
+async function findAsyncSequential(array, predicate) {
+    for (const t of array) {
+        if (await predicate(t)) {
+            return t;
+        }
+    }
+    return undefined;
+}
+exports.findAsyncSequential = findAsyncSequential;
+/**
+ * Takes a message and reports it according to the severity that the user wants.
+ *
+ * - `ignore`: completely no-op
+ * - `log`: uses the `INFO` log level
+ * - `warn`: uses the `WARN` log level
+ * - `error`: uses the `ERROR` log level
+ * - `throw`: aborts the process, throws the error.
+ *
+ * Since the logger doesn't have logging level filters yet, these severities
+ * mostly just differ by their colors.
+ *
+ * @throws In addition to throwing when `reportingSeverity === "throw"`, this
+ * function also throws if `reportingSeverity` is not one of the above.
+ */
+function reportMessage(message, reportingSeverity) {
+    switch (reportingSeverity) {
+        case 'ignore':
+            break;
+        case 'log':
+            logger_1.default.info(message);
+            break;
+        case 'warn':
+            logger_1.default.warn(message);
+            break;
+        case 'error':
+            logger_1.default.error(message);
+            break;
+        case 'throw':
+            throw new Error(message);
+        default:
+            throw new Error(`Unexpected "reportingSeverity" value: ${reportingSeverity}.`);
+    }
+}
+exports.reportMessage = reportMessage;
+//# sourceMappingURL=jsUtils.js.map

package/lib/jsUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsUtils.js","sourceRoot":"","sources":["../src/jsUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAGH,wEAAwC;AAExC,gDAAgD;AAChD,SAAgB,YAAY,CAAC,GAAW,EAAE,MAAc;IACtD,IAAI,MAAM,KAAK,EAAE,EAAE;QACjB,wBAAwB;QACxB,OAAO,GAAG,CAAC;KACZ;IACD,OAAO,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACnE,CAAC;AAND,oCAMC;AAED,gDAAgD;AAChD,SAAgB,YAAY,CAAC,GAAW,EAAE,MAAc;IACtD,OAAO,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACjE,CAAC;AAFD,oCAEC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,kBAAkB,CACtC,KAAU,EACV,MAA4B;IAE5B,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE;QACrB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;KACtB;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAVD,gDAUC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,mBAAmB,CACvC,KAAU,EACV,SAAqC;IAErC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE;QACrB,IAAI,MAAM,SAAS,CAAC,CAAC,CAAC,EAAE;YACtB,OAAO,CAAC,CAAC;SACV;KACF;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAVD,kDAUC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAC3B,OAAe,EACf,iBAAoC;IAEpC,QAAQ,iBAAiB,EAAE;QACzB,KAAK,QAAQ;YACX,MAAM;QACR,KAAK,KAAK;YACR,gBAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,MAAM;QACR,KAAK,MAAM;YACT,gBAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,MAAM;QACR,KAAK,OAAO;YACV,gBAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtB,MAAM;QACR,KAAK,OAAO;YACV,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3B;YACE,MAAM,IAAI,KAAK,CACb,yCAAyC,iBAAiB,GAAG,CAC9D,CAAC;KACL;AACH,CAAC;AAvBD,sCAuBC"}

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,CAuEA"}

package/lib/markdownLinks.js

@@ -7,35 +7,69 @@
  */
 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 = [
+                path_1.default.dirname(filePath),
+                ...(0, dataFileUtils_1.getContentPathList)(contentPaths),
+            ].map((p) => path_1.default.join(p, decodeURIComponent(mdLink)));
+            const aliasedSourceMatch = sourcesToTry
+                .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(mdLink, encodedPermalink);
             }
             else {
                 const brokenMarkdownLink = {
@@ -53,3 +87,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 must be composed of letters,
+ * underscores, and dashes only.
+ *
+ * @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;
+};
+/**
+ * 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,CAAC,EAAE,MAAM,CAAC;CACb,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;AAyBD,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 must be composed of letters,
+ * underscores, and dashes only.
+ *
+ * @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>[\w-]+)\}$/;
+    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(?:.|\n(?!\n))*\n{2,})*/, '')
+        .trim();
+    const regularTitleMatch = /^#[ \t]+(?<title>[^ \t].*)(?:\n|$)/.exec(contentWithoutImport);
+    const alternateTitleMatch = /^(?<title>.*)\n=+(?:\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