@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/lib/client/docsClientUtils.js

@@ -8,14 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDocVersionSuggestions = exports.getActiveDocContext = exports.getActiveVersion = exports.getLatestVersion = exports.getActivePlugin = void 0;
 const router_1 = require("@docusaurus/router");
+// get the data of the plugin that is currently "active"
+// ie the docs of that plugin are currently browsed
+// it is useful to support multiple docs plugin instances
 function getActivePlugin(allPluginDatas, pathname, options = {}) {
-    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => {
-        return !!router_1.matchPath(pathname, {
-            path: pluginData.path,
-            exact: false,
-            strict: false,
-        });
-    });
+    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => !!(0, router_1.matchPath)(pathname, {
+        path: pluginData.path,
+        exact: false,
+        strict: false,
+    }));
     const activePlugin = activeEntry
         ? { pluginId: activeEntry[0], pluginData: activeEntry[1] }
         : undefined;
@@ -27,32 +28,28 @@ function getActivePlugin(allPluginDatas, pathname, options = {}) {
     return activePlugin;
 }
 exports.getActivePlugin = getActivePlugin;
-const getLatestVersion = (data) => {
-    return data.versions.find((version) => version.isLast);
-};
+const getLatestVersion = (data) => data.versions.find((version) => version.isLast);
 exports.getLatestVersion = getLatestVersion;
 // Note: return undefined on doc-unrelated pages,
 // because there's no version currently considered as active
 const getActiveVersion = (data, pathname) => {
-    const lastVersion = exports.getLatestVersion(data);
+    const lastVersion = (0, exports.getLatestVersion)(data);
     // Last version is a route like /docs/*,
     // we need to try to match it last or it would match /docs/version-1.0/* as well
     const orderedVersionsMetadata = [
         ...data.versions.filter((version) => version !== lastVersion),
         lastVersion,
     ];
-    return orderedVersionsMetadata.find((version) => {
-        return !!router_1.matchPath(pathname, {
-            path: version.path,
-            exact: false,
-            strict: false,
-        });
-    });
+    return orderedVersionsMetadata.find((version) => !!(0, router_1.matchPath)(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+    }));
 };
 exports.getActiveVersion = getActiveVersion;
 const getActiveDocContext = (data, pathname) => {
-    const activeVersion = exports.getActiveVersion(data, pathname);
-    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!router_1.matchPath(pathname, {
+    const activeVersion = (0, exports.getActiveVersion)(data, pathname);
+    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!(0, router_1.matchPath)(pathname, {
         path: doc.path,
         exact: true,
         strict: false,
@@ -79,8 +76,8 @@ const getActiveDocContext = (data, pathname) => {
 };
 exports.getActiveDocContext = getActiveDocContext;
 const getDocVersionSuggestions = (data, pathname) => {
-    const latestVersion = exports.getLatestVersion(data);
-    const activeDocContext = exports.getActiveDocContext(data, pathname);
+    const latestVersion = (0, exports.getLatestVersion)(data);
+    const activeDocContext = (0, exports.getActiveDocContext)(data, pathname);
     const latestDocSuggestion = activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name];
     return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
 };

package/lib/docFrontMatter.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocFrontMatter } from './types';
+import type { DocFrontMatter } from './types';
 export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;

package/lib/docFrontMatter.js

@@ -7,10 +7,9 @@
  */
 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({
@@ -24,11 +23,16 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     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(),
+    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),
+    ...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/docs.d.ts

@@ -4,15 +4,37 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext } from '@docusaurus/types';
-import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata } from './types';
+import type { LoadContext } from '@docusaurus/types';
+import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata, LoadedVersion } from './types';
+import { SidebarsUtils } from './sidebars/utils';
 declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
 export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
-export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
 export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;
     options: MetadataOptions;
 }): DocMetadataBase;
+export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
+/**
+ * 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)
+ */
+export declare function getMainDocId({ docs, sidebarsUtils, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+}): string;
+export declare function isConventionalDocIndex(doc: {
+    source: DocMetadataBase['slug'];
+    sourceDirName: DocMetadataBase['sourceDirName'];
+}): boolean;
+export declare function getDocIds(doc: DocMetadataBase): [string, string];
+export declare function createDocsByIdIndex<Doc extends {
+    id: string;
+    unversionedId: string;
+}>(docs: Doc[]): Record<string, Doc>;
 export {};

package/lib/docs.js

@@ -6,25 +6,26 @@
  * 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.isConventionalDocIndex = 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 path_1 = (0, tslib_1.__importDefault)(require("path"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
 const lastUpdate_1 = require("./lastUpdate");
-const slug_1 = tslib_1.__importDefault(require("./slug"));
+const slug_1 = (0, 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 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 +41,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, versions_1.getDocsDirPaths)(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,8 +51,9 @@ 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)));
 }
@@ -59,23 +61,20 @@ exports.readVersionDocs = readVersionDocs;
 function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     var _a, _b, _c, _d, _e, _f;
     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, docFrontMatter_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;
+    // but allow to disable this behavior with frontmatter
+    parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
     // ex: api/plugins/myDoc -> myDoc
     // ex: myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
     // ex: api/plugins/myDoc -> api/plugins
     // ex: 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;
@@ -97,9 +96,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
             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 +106,26 @@ 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,
-        });
+    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 = (_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 permalink = (0, utils_1.normalizeUrl)([versionMetadata.versionPath, 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,
             });
@@ -143,7 +135,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
             const baseVersionEditUrl = isLocalized && options.editLocalizedFiles
                 ? versionMetadata.versionEditUrlLocalized
                 : versionMetadata.versionEditUrl;
-            return utils_1.getEditUrl(relativeFilePath, baseVersionEditUrl);
+            return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
         }
         else {
             return undefined;
@@ -156,14 +148,14 @@ 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,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+        tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
         version: versionMetadata.versionName,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -179,8 +171,100 @@ function processDocMetadata(args) {
         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}"`));
+        console.error(chalk_1.default.red(`Can't process doc metadata for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`));
         throw e;
     }
 }
 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);
+        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
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+            : (0, utils_2.toNavigationLink)(navigation.previous, docsById);
+        const next = doc.frontMatter.pagination_next
+            ? 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);
+        }
+        else {
+            return docs[0];
+        }
+    }
+    return getMainDoc().unversionedId;
+}
+exports.getMainDocId = getMainDocId;
+function getLastPathSegment(str) {
+    return (0, lodash_1.last)(str.split('/'));
+}
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// 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
+function isConventionalDocIndex(doc) {
+    // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
+    const docName = path_1.default.parse(doc.source).name;
+    // "folder/subFolder/subSubFolder" => "subSubFolder"
+    const lastDirName = getLastPathSegment(doc.sourceDirName);
+    const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+    return eligibleDocIndexNames.includes(docName.toLowerCase());
+}
+exports.isConventionalDocIndex = isConventionalDocIndex;
+// 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 {
+        ...(0, lodash_1.keyBy)(docs, (doc) => doc.unversionedId),
+        ...(0, lodash_1.keyBy)(docs, (doc) => doc.id),
+    };
+}
+exports.createDocsByIdIndex = createDocsByIdIndex;

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';
+import type { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
 export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

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 type { LoadContext, Plugin } from '@docusaurus/types';
 import { PluginOptions, LoadedContent } from './types';
 export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
 export { validateOptions } from './options';