@docusaurus/plugin-content-docs 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/lib/versions.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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 { PluginOptions, VersionMetadata } from './types';
-import { LoadContext } from '@docusaurus/types';
-export declare function getVersionedDocsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionedSidebarsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
-export declare function readVersionsMetadata({ context, options, }: {
-    context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
-    options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
-}): VersionMetadata[];
-export declare function getDocsDirPaths(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>): [string, string];

package/lib/versions.js

@@ -1,287 +0,0 @@
-"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.getDocsDirPaths = exports.readVersionsMetadata = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = 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 constants_1 = require("./constants");
-const constants_2 = require("@docusaurus/core/lib/constants");
-const utils_1 = require("@docusaurus/utils");
-const lodash_1 = require("lodash");
-// retro-compatibility: no prefix for the default plugin id
-function addPluginIdPrefix(fileOrDir, pluginId) {
-    if (pluginId === constants_2.DEFAULT_PLUGIN_ID) {
-        return fileOrDir;
-    }
-    else {
-        return `${pluginId}_${fileOrDir}`;
-    }
-}
-function getVersionedDocsDirPath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId));
-}
-exports.getVersionedDocsDirPath = getVersionedDocsDirPath;
-function getVersionedSidebarsDirPath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId));
-}
-exports.getVersionedSidebarsDirPath = getVersionedSidebarsDirPath;
-function getVersionsFilePath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));
-}
-exports.getVersionsFilePath = getVersionsFilePath;
-function ensureValidVersionString(version) {
-    if (typeof version !== 'string') {
-        throw new Error(`versions should be strings. Found type=[${typeof version}] for version=[${version}]`);
-    }
-    // Should we forbid versions with special chars like / ?
-    if (version.trim().length === 0) {
-        throw new Error(`Invalid version=[${version}]`);
-    }
-}
-function ensureValidVersionArray(versionArray) {
-    if (!(versionArray instanceof Array)) {
-        throw new Error(`The versions file should contain an array of versions! Found content=${JSON.stringify(versionArray)}`);
-    }
-    versionArray.forEach(ensureValidVersionString);
-}
-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir, pluginId) {
-    const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-    if (fs_extra_1.default.existsSync(versionsFilePath)) {
-        const content = JSON.parse(fs_extra_1.default.readFileSync(versionsFilePath, 'utf8'));
-        ensureValidVersionArray(content);
-        return content;
-    }
-    else {
-        return null;
-    }
-}
-// TODO not easy to make async due to many deps
-function readVersionNames(siteDir, options) {
-    const versionFileContent = readVersionsFile(siteDir, options.id);
-    if (!versionFileContent && options.disableVersioning) {
-        throw new Error(`Docs: using disableVersioning=${options.disableVersioning} option on a non-versioned site does not make sense`);
-    }
-    const versions = options.disableVersioning ? [] : versionFileContent !== null && versionFileContent !== void 0 ? versionFileContent : [];
-    // We add the current version at the beginning, unless
-    // - user don't want to
-    // - it's been explicitly added to versions.json
-    if (options.includeCurrentVersion &&
-        !versions.includes(constants_1.CURRENT_VERSION_NAME)) {
-        versions.unshift(constants_1.CURRENT_VERSION_NAME);
-    }
-    if (versions.length === 0) {
-        throw new Error(`It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=${options.includeCurrentVersion} disableVersioning=${options.disableVersioning}`);
-    }
-    return versions;
-}
-function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
-    return utils_1.getPluginI18nPath({
-        siteDir,
-        locale,
-        pluginName: 'docusaurus-plugin-content-docs',
-        pluginId,
-        subPaths: [
-            versionName === constants_1.CURRENT_VERSION_NAME
-                ? constants_1.CURRENT_VERSION_NAME
-                : `version-${versionName}`,
-        ],
-    });
-}
-function getVersionMetadataPaths({ versionName, context, options, }) {
-    const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    const contentPath = isCurrentVersion
-        ? path_1.default.resolve(context.siteDir, options.path)
-        : path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`);
-    const contentPathLocalized = getDocsDirPathLocalized({
-        siteDir: context.siteDir,
-        locale: context.i18n.currentLocale,
-        pluginId: options.id,
-        versionName,
-    });
-    function getSidebarFilePath() {
-        if (isCurrentVersion) {
-            return options.sidebarPath
-                ? path_1.default.resolve(context.siteDir, options.sidebarPath)
-                : options.sidebarPath;
-        }
-        else {
-            return path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`);
-        }
-    }
-    return {
-        contentPath,
-        contentPathLocalized,
-        sidebarFilePath: getSidebarFilePath(),
-    };
-}
-function getVersionEditUrls({ contentPath, contentPathLocalized, context: { siteDir, i18n }, options: { id, path: currentVersionPath, editUrl, editCurrentVersion }, }) {
-    if (!editUrl) {
-        return undefined;
-    }
-    // if the user is using the functional form of editUrl,
-    // he has total freedom and we can't compute a "version edit url"
-    if (typeof editUrl === 'function') {
-        return undefined;
-    }
-    const editDirPath = editCurrentVersion ? currentVersionPath : contentPath;
-    const editDirPathLocalized = editCurrentVersion
-        ? getDocsDirPathLocalized({
-            siteDir,
-            locale: i18n.currentLocale,
-            versionName: constants_1.CURRENT_VERSION_NAME,
-            pluginId: id,
-        })
-        : contentPathLocalized;
-    const versionPathSegment = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
-    const versionPathSegmentLocalized = utils_1.posixPath(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
-    const versionEditUrl = utils_1.normalizeUrl([editUrl, versionPathSegment]);
-    const versionEditUrlLocalized = utils_1.normalizeUrl([
-        editUrl,
-        versionPathSegmentLocalized,
-    ]);
-    return {
-        versionEditUrl,
-        versionEditUrlLocalized,
-    };
-}
-function createVersionMetadata({ versionName, isLast, context, options, }) {
-    var _a, _b, _c;
-    const { sidebarFilePath, contentPath, contentPathLocalized, } = getVersionMetadataPaths({
-        versionName,
-        context,
-        options,
-    });
-    // retro-compatible values
-    const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
-    const defaultVersionPathPart = isLast
-        ? ''
-        : versionName === constants_1.CURRENT_VERSION_NAME
-            ? 'next'
-            : versionName;
-    const versionOptions = (_a = options.versions[versionName]) !== null && _a !== void 0 ? _a : {};
-    const versionLabel = (_b = versionOptions.label) !== null && _b !== void 0 ? _b : defaultVersionLabel;
-    const versionPathPart = (_c = versionOptions.path) !== null && _c !== void 0 ? _c : defaultVersionPathPart;
-    const versionPath = utils_1.normalizeUrl([
-        context.baseUrl,
-        options.routeBasePath,
-        versionPathPart,
-    ]);
-    const versionEditUrls = getVersionEditUrls({
-        contentPath,
-        contentPathLocalized,
-        context,
-        options,
-    });
-    // Because /docs/:route` should always be after `/docs/versionName/:route`.
-    const routePriority = versionPathPart === '' ? -1 : undefined;
-    return {
-        versionName,
-        versionLabel,
-        versionPath,
-        versionEditUrl: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrl,
-        versionEditUrlLocalized: versionEditUrls === null || versionEditUrls === void 0 ? void 0 : versionEditUrls.versionEditUrlLocalized,
-        isLast,
-        routePriority,
-        sidebarFilePath,
-        contentPath,
-        contentPathLocalized,
-    };
-}
-function checkVersionMetadataPaths({ versionMetadata, context, }) {
-    const { versionName, contentPath, sidebarFilePath } = versionMetadata;
-    const { siteDir } = context;
-    const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    if (!fs_extra_1.default.existsSync(contentPath)) {
-        throw new Error(`The docs folder does not exist for version [${versionName}]. A docs folder is expected to be found at ${path_1.default.relative(siteDir, contentPath)}`);
-    }
-    // If the current version defines a path to a sidebar file  that does not exist, we throw!
-    // Note: for versioned sidebars, the file may not exist (as we prefer to not create it rather than to create an empty file)
-    // See https://github.com/facebook/docusaurus/issues/3366
-    // See https://github.com/facebook/docusaurus/pull/4775
-    if (isCurrentVersion &&
-        typeof sidebarFilePath === 'string' &&
-        !fs_extra_1.default.existsSync(sidebarFilePath)) {
-        throw new Error(`The path to the sidebar file does not exist at [${path_1.default.relative(siteDir, sidebarFilePath)}].
-Please set the docs [sidebarPath] field in your config file to:
-- a sidebars path that exists
-- false: to disable the sidebar
-- undefined: for Docusaurus generates it automatically`);
-    }
-}
-// TODO for retrocompatibility with existing behavior
-// We should make this configurable
-// "last version" is not a very good concept nor api surface
-function getDefaultLastVersionName(versionNames) {
-    if (versionNames.length === 1) {
-        return versionNames[0];
-    }
-    else {
-        return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
-    }
-}
-function checkVersionsOptions(availableVersionNames, options) {
-    const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
-    if (options.lastVersion &&
-        !availableVersionNames.includes(options.lastVersion)) {
-        throw new Error(`Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
-    }
-    const unknownVersionConfigNames = lodash_1.difference(Object.keys(options.versions), availableVersionNames);
-    if (unknownVersionConfigNames.length > 0) {
-        throw new Error(`Bad docs options.versions: unknown versions found: ${unknownVersionConfigNames.join(',')}. ${availableVersionNamesMsg}`);
-    }
-    if (options.onlyIncludeVersions) {
-        if (options.onlyIncludeVersions.length === 0) {
-            throw new Error(`Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed`);
-        }
-        const unknownOnlyIncludeVersionNames = lodash_1.difference(options.onlyIncludeVersions, availableVersionNames);
-        if (unknownOnlyIncludeVersionNames.length > 0) {
-            throw new Error(`Bad docs options.onlyIncludeVersions: unknown versions found: ${unknownOnlyIncludeVersionNames.join(',')}. ${availableVersionNamesMsg}`);
-        }
-        if (options.lastVersion &&
-            !options.onlyIncludeVersions.includes(options.lastVersion)) {
-            throw new Error(`Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array`);
-        }
-    }
-}
-// Filter versions according to provided options
-// Note: we preserve the order in which versions are provided
-// the order of the onlyIncludeVersions array does not matter
-function filterVersions(versionNamesUnfiltered, options) {
-    if (options.onlyIncludeVersions) {
-        return versionNamesUnfiltered.filter((name) => (options.onlyIncludeVersions || []).includes(name));
-    }
-    else {
-        return versionNamesUnfiltered;
-    }
-}
-// TODO make this async (requires plugin init to be async)
-function readVersionsMetadata({ context, options, }) {
-    var _a;
-    const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
-    checkVersionsOptions(versionNamesUnfiltered, options);
-    const versionNames = filterVersions(versionNamesUnfiltered, options);
-    const lastVersionName = (_a = options.lastVersion) !== null && _a !== void 0 ? _a : getDefaultLastVersionName(versionNames);
-    const versionsMetadata = versionNames.map((versionName) => createVersionMetadata({
-        versionName,
-        isLast: versionName === lastVersionName,
-        context,
-        options,
-    }));
-    versionsMetadata.forEach((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context }));
-    return versionsMetadata;
-}
-exports.readVersionsMetadata = readVersionsMetadata;
-// order matter!
-// Read in priority the localized path, then the unlocalized one
-// We want the localized doc to "override" the unlocalized one
-function getDocsDirPaths(versionMetadata) {
-    return [versionMetadata.contentPathLocalized, versionMetadata.contentPath];
-}
-exports.getDocsDirPaths = getDocsDirPaths;

package/src/__tests__/__fixtures__/bad-id-site/docs/invalid-id.md

@@ -1,5 +0,0 @@
----
-id: hello/super
----
-
-Lorem

package/src/__tests__/__fixtures__/bad-slug-on-doc-home-site/docs/docWithSlug.md

@@ -1,5 +0,0 @@
----
-slug: docWithSlug.html
----
-
-Lorem

package/src/__tests__/__fixtures__/empty-site/docusaurus.config.js

@@ -1,16 +0,0 @@
-/**
- * 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.
- */
-
-module.exports = {
-  title: 'My Site',
-  tagline: 'The tagline of my site',
-  url: 'https://your-docusaurus-test-site.com',
-  baseUrl: '/',
-  favicon: 'img/favicon.ico',
-  organizationName: 'facebook', // Usually your GitHub org/user name.
-  projectName: 'docusaurus', // Usually your repo name.
-};

package/src/__tests__/__fixtures__/empty-site/sidebars.json

@@ -1 +0,0 @@
-{}

package/src/__tests__/__fixtures__/sidebars/sidebars-category-shorthand.js

@@ -1,34 +0,0 @@
-/**
- * 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.
- */
-
-module.exports = {
-  docs: [
-    {
-      'level 1': [
-        'a',
-        {
-          'level 2': [
-            {
-              'level 3': [
-                'c',
-                {
-                  'level 4': [
-                    'd',
-                    {
-                      'deeper more more': ['e'],
-                    },
-                  ],
-                },
-              ],
-            },
-            'f',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-items.json

@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "category",
-        "label": "Category Label",
-        "items": "doc1"
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-category-wrong-label.json

@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "category",
-        "label": true,
-        "items": ["doc1"]
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-category.js

@@ -1,44 +0,0 @@
-/*
- * 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.
- */
-
-module.exports = {
-  docs: [
-    {
-      type: 'category',
-      label: 'level 1',
-      items: [
-        'a',
-        {
-          type: 'category',
-          label: 'level 2',
-          items: [
-            {
-              type: 'category',
-              label: 'level 3',
-              items: [
-                'c',
-                {
-                  type: 'category',
-                  label: 'level 4',
-                  items: [
-                    'd',
-                    {
-                      type: 'category',
-                      label: 'deeper more more',
-                      items: ['e'],
-                    },
-                  ],
-                },
-              ],
-            },
-            'f',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/src/__tests__/__fixtures__/sidebars/sidebars-collapsed-first-level.json

@@ -1,20 +0,0 @@
-{
-    "docs": [
-        {
-            "type": "category",
-            "label": "Introduction",
-            "items": [
-                "doc1"
-            ],
-            "collapsed": false
-        },
-        {
-            "type": "category",
-            "label": "Powering MDX",
-            "items": [
-                "doc2"
-            ],
-            "collapsed": false
-        }
-    ]
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-collapsed.json

@@ -1,21 +0,0 @@
-{
-    "docs": {
-      "Test": [
-        {
-          "type": "category",
-          "label": "Introduction",
-          "items": ["doc1"],
-          "collapsed": false
-        }
-      ],
-      "Reference": [
-        {
-          "type": "category",
-          "label": "Powering MDX",
-          "items": ["doc2"],
-          "collapsed": false
-        }
-      ]
-    }
-  }
-  

package/src/__tests__/__fixtures__/sidebars/sidebars-doc-id-not-string.json

@@ -1,10 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "doc",
-        "id": ["doc1"]
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-href.json

@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "link",
-        "label": "GitHub",
-        "href": ["example.com"]
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-link-wrong-label.json

@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "link",
-        "label": false,
-        "href": "https://github.com"
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-link.json

@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      {
-        "type": "link",
-        "label": "category",
-        "href": "https://github.com"
-      }
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-unknown-type.json

@@ -1,14 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      "foo/bar",
-      "foo/baz",
-      {
-        "type": "superman"
-      }
-    ],
-    "Guides": [
-      "hello"
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars-wrong-field.json

@@ -1,20 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      "foo/bar",
-      "foo/baz",
-      {
-        "type": "category",
-        "label": "category",
-        "href": "https://github.com"
-      },
-      {
-        "type": "ref",
-        "id": "hello"
-      }
-    ],
-    "Guides": [
-      "hello"
-    ]
-  }
-}

package/src/__tests__/__fixtures__/sidebars/sidebars.json

@@ -1,20 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      "foo/bar",
-      "foo/baz",
-      {
-        "type": "link",
-        "label": "Github",
-        "href": "https://github.com"
-      },
-      {
-        "type": "ref",
-        "id": "hello"
-      }
-    ],
-    "Guides": [
-      "hello"
-    ]
-  }
-}

package/src/__tests__/__fixtures__/simple-site/docs/foo/bar.md

@@ -1,69 +0,0 @@
----
-id: bar
-title: Bar
-description: This is custom description
----
-
-# Remarkable
-
-> Experience real-time editing with Remarkable!
-
-Click the `clear` link to start with a clean slate, or get the `permalink` to share or save your results.
-
----
-
-# h1 Heading
-
-## h2 Heading
-
-### h3 Heading
-
-#### h4 Heading
-
-##### h5 Heading
-
-###### h6 Heading
-
-## Horizontal Rules
-
----
-
----
-
----
-
-## Typographic replacements
-
-Enable typographer option to see result.
-
-(c) (C) (r) (R) (tm) (TM) (p) (P) +-
-
-test.. test... test..... test?..... test!....
-
-!!!!!! ???? ,,
-
-Remarkable -- awesome
-
-"Smartypants, double quotes"
-
-'Smartypants, single quotes'
-
-## Emphasis
-
-**This is bold text**
-
-**This is bold text**
-
-_This is italic text_
-
-_This is italic text_
-
-~~Deleted text~~
-
-Superscript: 19^th^
-
-Subscript: H~2~O
-
-++Inserted text++
-
-==Marked text==