@docusaurus/plugin-content-docs 2.0.0-beta.1ec2c95e3 → 2.0.0-beta.21

package/lib/docs.js

@@ -6,25 +6,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const lastUpdate_1 = require("./lastUpdate");
 const slug_1 = tslib_1.__importDefault(require("./slug"));
 const constants_1 = require("./constants");
-const globby_1 = tslib_1.__importDefault(require("globby"));
-const versions_1 = require("./versions");
 const numberPrefix_1 = require("./numberPrefix");
-const docFrontMatter_1 = require("./docFrontMatter");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const frontMatter_1 = require("./frontMatter");
+const utils_2 = require("./sidebars/utils");
 async function readLastUpdateData(filePath, options) {
     const { showLastUpdateAuthor, showLastUpdateTime } = options;
     if (showLastUpdateAuthor || showLastUpdateTime) {
         // Use fake data in dev for faster development.
         const fileLastUpdateData = process.env.NODE_ENV === 'production'
-            ? await lastUpdate_1.getFileLastUpdate(filePath)
+            ? await (0, lastUpdate_1.getFileLastUpdate)(filePath)
             : {
                 author: 'Author',
                 timestamp: 1539502055,
@@ -40,7 +39,7 @@ async function readLastUpdateData(filePath, options) {
     return {};
 }
 async function readDocFile(versionMetadata, source, options) {
-    const contentPath = await utils_1.getFolderContainingFile(versions_1.getDocsDirPaths(versionMetadata), source);
+    const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(versionMetadata), source);
     const filePath = path_1.default.join(contentPath, source);
     const [content, lastUpdate] = await Promise.all([
         fs_extra_1.default.readFile(filePath, 'utf-8'),
@@ -50,40 +49,41 @@ async function readDocFile(versionMetadata, source, options) {
 }
 exports.readDocFile = readDocFile;
 async function readVersionDocs(versionMetadata, options) {
-    const sources = await globby_1.default(options.include, {
+    const sources = await (0, utils_1.Globby)(options.include, {
         cwd: versionMetadata.contentPath,
+        ignore: options.exclude,
     });
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
 }
 exports.readVersionDocs = readVersionDocs;
-function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
-    var _a, _b, _c, _d, _e, _f;
+/** Docs with draft front matter are only considered draft in production. */
+function isDraftForEnvironment({ env, frontMatter, }) {
+    return (env === 'production' && frontMatter.draft) ?? false;
+}
+function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
     const { source, content, lastUpdate, contentPath, filePath } = docFile;
-    const { homePageId } = options;
     const { siteDir, i18n } = context;
-    const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = utils_1.parseMarkdownString(content);
-    const frontMatter = docFrontMatter_1.validateDocFrontMatter(unsafeFrontMatter);
+    const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
+    const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
     const { custom_edit_url: customEditURL, 
-    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
-    // but allow to disable this behavior with frontmatterr
-    // eslint-disable-next-line camelcase
-    parse_number_prefixes = true, } = frontMatter;
-    // ex: api/plugins/myDoc -> myDoc
-    // ex: myDoc -> myDoc
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
+    // but allow to disable this behavior with front matter
+    parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
+    // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
-    // ex: api/plugins/myDoc -> api/plugins
-    // ex: myDoc -> .
+    // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
     const sourceDirName = path_1.default.dirname(source);
-    // eslint-disable-next-line camelcase
-    const { filename: unprefixedFileName, numberPrefix } = parse_number_prefixes
+    const { filename: unprefixedFileName, numberPrefix } = parseNumberPrefixes
         ? options.numberPrefixParser(sourceFileNameWithoutExtension)
         : { filename: sourceFileNameWithoutExtension, numberPrefix: undefined };
-    const baseID = (_a = frontMatter.id) !== null && _a !== void 0 ? _a : unprefixedFileName;
+    const baseID = frontMatter.id ?? unprefixedFileName;
     if (baseID.includes('/')) {
         throw new Error(`Document id "${baseID}" cannot include slash.`);
     }
-    // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
-    const sidebarPosition = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
+    // For autogenerated sidebars, sidebar position can come from filename number
+    // prefix or front matter
+    const sidebarPosition = frontMatter.sidebar_position ?? numberPrefix;
     // TODO legacy retrocompatibility
     // The same doc in 2 distinct version could keep the same id,
     // we just need to namespace the data by version
@@ -91,15 +91,14 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         ? undefined
         : `version-${versionMetadata.versionName}`;
     // TODO legacy retrocompatibility
-    // I think it's bad to affect the frontmatter id with the dirname?
+    // I think it's bad to affect the front matter id with the dirname?
     function computeDirNameIdPrefix() {
         if (sourceDirName === '.') {
             return undefined;
         }
         // Eventually remove the number prefixes from intermediate directories
-        // eslint-disable-next-line camelcase
-        return parse_number_prefixes
-            ? numberPrefix_1.stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
+        return parseNumberPrefixes
+            ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, options.numberPrefixParser)
             : sourceDirName;
     }
     const unversionedId = [computeDirNameIdPrefix(), baseID]
@@ -108,32 +107,27 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     // TODO is versioning the id very useful in practice?
     // legacy versioned id, requires a breaking change to modify this
     const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
-    // TODO remove soon, deprecated homePageId
-    const isDocsHomePage = unversionedId === (homePageId !== null && homePageId !== void 0 ? homePageId : '_index');
-    if (frontMatter.slug && isDocsHomePage) {
-        throw new Error(`The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to choose either homePageId or slug, not both`);
-    }
-    const docSlug = isDocsHomePage
-        ? '/'
-        : slug_1.default({
-            baseID,
-            dirName: sourceDirName,
-            frontmatterSlug: frontMatter.slug,
-            stripDirNumberPrefixes: parse_number_prefixes,
-            numberPrefixParser: options.numberPrefixParser,
-        });
-    // Note: the title is used by default for page title, sidebar label, pagination buttons...
-    // frontMatter.title should be used in priority over contentTitle (because it can contain markdown/JSX syntax)
-    const title = (_d = (_c = frontMatter.title) !== null && _c !== void 0 ? _c : contentTitle) !== null && _d !== void 0 ? _d : baseID;
-    const description = (_f = (_e = frontMatter.description) !== null && _e !== void 0 ? _e : excerpt) !== null && _f !== void 0 ? _f : '';
-    const permalink = utils_1.normalizeUrl([versionMetadata.versionPath, docSlug]);
+    const docSlug = (0, slug_1.default)({
+        baseID,
+        source,
+        sourceDirName,
+        frontMatterSlug: frontMatter.slug,
+        stripDirNumberPrefixes: parseNumberPrefixes,
+        numberPrefixParser: options.numberPrefixParser,
+    });
+    // Note: the title is used by default for page title, sidebar label,
+    // pagination buttons... frontMatter.title should be used in priority over
+    // contentTitle (because it can contain markdown/JSX syntax)
+    const title = frontMatter.title ?? contentTitle ?? baseID;
+    const description = frontMatter.description ?? excerpt ?? '';
+    const permalink = (0, utils_1.normalizeUrl)([versionMetadata.path, docSlug]);
     function getDocEditUrl() {
         const relativeFilePath = path_1.default.relative(contentPath, filePath);
         if (typeof options.editUrl === 'function') {
             return options.editUrl({
                 version: versionMetadata.versionName,
-                versionDocsDirPath: utils_1.posixPath(path_1.default.relative(siteDir, versionMetadata.contentPath)),
-                docPath: utils_1.posixPath(relativeFilePath),
+                versionDocsDirPath: (0, utils_1.posixPath)(path_1.default.relative(siteDir, versionMetadata.contentPath)),
+                docPath: (0, utils_1.posixPath)(relativeFilePath),
                 permalink,
                 locale: context.i18n.currentLocale,
             });
@@ -141,14 +135,13 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         else if (typeof options.editUrl === 'string') {
             const isLocalized = contentPath === versionMetadata.contentPathLocalized;
             const baseVersionEditUrl = isLocalized && options.editLocalizedFiles
-                ? versionMetadata.versionEditUrlLocalized
-                : versionMetadata.versionEditUrl;
-            return utils_1.getEditUrl(relativeFilePath, baseVersionEditUrl);
-        }
-        else {
-            return undefined;
+                ? versionMetadata.editUrlLocalized
+                : versionMetadata.editUrl;
+            return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
         }
+        return undefined;
     }
+    const draft = isDraftForEnvironment({ env, frontMatter });
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
     // Adding properties to object after instantiation will cause hidden
@@ -156,19 +149,22 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     return {
         unversionedId,
         id,
-        isDocsHomePage,
         title,
         description,
-        source: utils_1.aliasedSitePath(filePath, siteDir),
+        source: (0, utils_1.aliasedSitePath)(filePath, siteDir),
         sourceDirName,
         slug: docSlug,
         permalink,
+        draft,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+        tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
         version: versionMetadata.versionName,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,
         formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
-            ? new Intl.DateTimeFormat(i18n.currentLocale).format(lastUpdate.lastUpdatedAt * 1000)
+            ? new Intl.DateTimeFormat(i18n.currentLocale, {
+                calendar: i18n.localeConfigs[i18n.currentLocale].calendar,
+            }).format(lastUpdate.lastUpdatedAt * 1000)
             : undefined,
         sidebarPosition,
         frontMatter,
@@ -178,9 +174,114 @@ function processDocMetadata(args) {
     try {
         return doProcessDocMetadata(args);
     }
-    catch (e) {
-        console.error(chalk_1.default.red(`Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`));
-        throw e;
+    catch (err) {
+        logger_1.default.error `Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`;
+        throw err;
     }
 }
 exports.processDocMetadata = processDocMetadata;
+function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
+    const docsById = createDocsByIdIndex(docsBase);
+    sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
+    // Add sidebar/next/previous to the docs
+    function addNavData(doc) {
+        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id, doc.frontMatter.displayed_sidebar);
+        const toNavigationLinkByDocId = (docId, type) => {
+            if (!docId) {
+                return undefined;
+            }
+            const navDoc = docsById[docId];
+            if (!navDoc) {
+                // This could only happen if user provided the ID through front matter
+                throw new Error(`Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`);
+            }
+            return (0, utils_2.toDocNavigationLink)(navDoc);
+        };
+        const previous = doc.frontMatter.pagination_prev !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+            : (0, utils_2.toNavigationLink)(navigation.previous, docsById);
+        const next = doc.frontMatter.pagination_next !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+            : (0, utils_2.toNavigationLink)(navigation.next, docsById);
+        return { ...doc, sidebar: navigation.sidebarName, previous, next };
+    }
+    const docsWithNavigation = docsBase.map(addNavData);
+    // Sort to ensure consistent output for tests
+    docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
+    return docsWithNavigation;
+}
+exports.addDocNavigation = addDocNavigation;
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+function getMainDocId({ docs, sidebarsUtils, }) {
+    function getMainDoc() {
+        const versionHomeDoc = docs.find((doc) => doc.slug === '/');
+        const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
+        if (versionHomeDoc) {
+            return versionHomeDoc;
+        }
+        else if (firstDocIdOfFirstSidebar) {
+            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
+                doc.unversionedId === firstDocIdOfFirstSidebar);
+        }
+        return docs[0];
+    }
+    return getMainDoc().unversionedId;
+}
+exports.getMainDocId = getMainDocId;
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// This function is the default implementation of this convention
+//
+// Those index docs produce a different behavior
+// - Slugs do not end with a weird "/index" suffix
+// - Auto-generated sidebar categories link to them as intro
+const isCategoryIndex = ({ fileName, directories, }) => {
+    const eligibleDocIndexNames = [
+        'index',
+        'readme',
+        directories[0]?.toLowerCase(),
+    ];
+    return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+exports.isCategoryIndex = isCategoryIndex;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
+function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
+    // source + sourceDirName are always posix-style
+    return {
+        fileName: path_1.default.posix.parse(source).name,
+        extension: path_1.default.posix.parse(source).ext,
+        directories: sourceDirName.split(path_1.default.posix.sep).reverse(),
+    };
+}
+exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
+// Return both doc ids
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
+function getDocIds(doc) {
+    return [doc.unversionedId, doc.id];
+}
+exports.getDocIds = getDocIds;
+// Docs are indexed by both versioned and unversioned ids at the same time
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
+function createDocsByIdIndex(docs) {
+    return Object.fromEntries(docs.flatMap((doc) => [
+        [doc.unversionedId, doc],
+        [doc.id, doc],
+    ]));
+}
+exports.createDocsByIdIndex = createDocsByIdIndex;

package/{src/__tests__/__fixtures__/site-with-autogenerated-sidebar/docusaurus.config.js → lib/frontMatter.d.ts}

@@ -4,11 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
-module.exports = {
-  title: 'My Site',
-  tagline: 'The tagline of my site',
-  url: 'https://your-docusaurus-test-site.com',
-  baseUrl: '/',
-  favicon: 'img/favicon.ico',
-};
+import type { DocFrontMatter } from '@docusaurus/plugin-content-docs';
+export declare function validateDocFrontMatter(frontMatter: {
+    [key: string]: unknown;
+}): DocFrontMatter;

package/lib/{docFrontMatter.js → frontMatter.js}

@@ -7,28 +7,37 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocFrontMatter = void 0;
-/* eslint-disable camelcase */
 const utils_validation_1 = require("@docusaurus/utils-validation");
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     id: utils_validation_1.JoiFrontMatter.string(),
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     title: utils_validation_1.JoiFrontMatter.string().allow(''),
     hide_title: utils_validation_1.JoiFrontMatter.boolean(),
     hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
     keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
     image: utils_validation_1.URISchema,
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     slug: utils_validation_1.JoiFrontMatter.string(),
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
     sidebar_position: utils_validation_1.JoiFrontMatter.number(),
+    sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_custom_props: utils_validation_1.JoiFrontMatter.object().unknown(),
+    displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
+    tags: utils_validation_1.FrontMatterTagsSchema,
     pagination_label: utils_validation_1.JoiFrontMatter.string(),
     custom_edit_url: utils_validation_1.URISchema.allow('', null),
     parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
+    pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
+    pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
+    draft: utils_validation_1.JoiFrontMatter.boolean(),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
 }).unknown();
 function validateDocFrontMatter(frontMatter) {
-    return utils_validation_1.validateFrontMatter(frontMatter, DocFrontMatterSchema);
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
 }
 exports.validateDocFrontMatter = validateDocFrontMatter;

package/lib/globalData.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
-export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
-export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;
+import type { FullVersion } from './types';
+import type { GlobalVersion } from '@docusaurus/plugin-content-docs/client';
+export declare function toGlobalDataVersion(version: FullVersion): GlobalVersion;

package/lib/globalData.js

@@ -6,7 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = exports.toGlobalDataDoc = void 0;
+exports.toGlobalDataVersion = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const docs_1 = require("./docs");
 function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
@@ -14,15 +17,41 @@ function toGlobalDataDoc(doc) {
         sidebar: doc.sidebar,
     };
 }
-exports.toGlobalDataDoc = toGlobalDataDoc;
+function toGlobalDataGeneratedIndex(doc) {
+    return {
+        id: doc.slug,
+        path: doc.permalink,
+        sidebar: doc.sidebar,
+    };
+}
+function toGlobalSidebars(sidebars, version) {
+    return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
+        const firstLink = version.sidebarsUtils.getFirstLink(sidebarId);
+        if (!firstLink) {
+            return {};
+        }
+        return {
+            link: {
+                path: firstLink.type === 'generated-index'
+                    ? firstLink.permalink
+                    : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
+                label: firstLink.label,
+            },
+        };
+    });
+}
 function toGlobalDataVersion(version) {
     return {
         name: version.versionName,
-        label: version.versionLabel,
+        label: version.label,
         isLast: version.isLast,
-        path: version.versionPath,
-        mainDocId: version.mainDocId,
-        docs: version.docs.map(toGlobalDataDoc),
+        path: version.path,
+        mainDocId: (0, docs_1.getMainDocId)(version),
+        docs: version.docs
+            .map(toGlobalDataDoc)
+            .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+        draftIds: version.drafts.map((doc) => doc.unversionedId),
+        sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }
 exports.toGlobalDataVersion = toGlobalDataVersion;

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext, Plugin } from '@docusaurus/types';
-import { PluginOptions, LoadedContent } from './types';
-export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
+import type { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-docs';
+import type { LoadContext, Plugin } from '@docusaurus/types';
+export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Promise<Plugin<LoadedContent>>;
 export { validateOptions } from './options';