@docusaurus/plugin-content-docs 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/markdown/__tests__/linkify.test.ts

@@ -1,190 +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 fs from 'fs-extra';
-import path from 'path';
-import {linkify} from '../linkify';
-import {
-  DocsMarkdownOption,
-  SourceToPermalink,
-  VersionMetadata,
-  BrokenMarkdownLink,
-} from '../../types';
-import {VERSIONED_DOCS_DIR, CURRENT_VERSION_NAME} from '../../constants';
-
-function createFakeVersion({
-  versionName,
-  contentPath,
-  contentPathLocalized,
-}: {
-  versionName: string;
-  contentPath: string;
-  contentPathLocalized: string;
-}): VersionMetadata {
-  return {
-    versionName,
-    versionLabel: 'Any',
-    versionPath: 'any',
-    contentPath,
-    contentPathLocalized,
-    sidebarFilePath: 'any',
-    routePriority: undefined,
-    isLast: false,
-  };
-}
-
-const siteDir = path.join(__dirname, '__fixtures__');
-
-const versionCurrent = createFakeVersion({
-  versionName: CURRENT_VERSION_NAME,
-  contentPath: path.join(siteDir, 'docs'),
-  contentPathLocalized: path.join(
-    siteDir,
-    'i18n',
-    'fr',
-    'docusaurus-plugin-content-docs',
-    CURRENT_VERSION_NAME,
-  ),
-});
-
-const version100 = createFakeVersion({
-  versionName: '1.0.0',
-  contentPath: path.join(siteDir, VERSIONED_DOCS_DIR, 'version-1.0.0'),
-  contentPathLocalized: path.join(
-    siteDir,
-    'i18n',
-    'fr',
-    'docusaurus-plugin-content-docs',
-    'version-1.0.0',
-  ),
-});
-
-const sourceToPermalink: SourceToPermalink = {
-  '@site/docs/doc1.md': '/docs/doc1',
-  '@site/docs/doc2.md': '/docs/doc2',
-  '@site/docs/subdir/doc3.md': '/docs/subdir/doc3',
-  '@site/docs/doc4.md': '/docs/doc4',
-  '@site/versioned_docs/version-1.0.0/doc2.md': '/docs/1.0.0/doc2',
-  '@site/versioned_docs/version-1.0.0/subdir/doc1.md':
-    '/docs/1.0.0/subdir/doc1',
-
-  '@site/i18n/fr/docusaurus-plugin-content-docs/current/doc-localized.md':
-    '/fr/doc-localized',
-  '@site/docs/doc-localized': '/doc-localized',
-};
-
-function createMarkdownOptions(
-  options?: Partial<DocsMarkdownOption>,
-): DocsMarkdownOption {
-  return {
-    sourceToPermalink,
-    onBrokenMarkdownLink: () => {},
-    versionsMetadata: [versionCurrent, version100],
-    siteDir,
-    ...options,
-  };
-}
-
-const transform = (filepath: string, options?: Partial<DocsMarkdownOption>) => {
-  const markdownOptions = createMarkdownOptions(options);
-  const content = fs.readFileSync(filepath, 'utf-8');
-  const transformedContent = linkify(content, filepath, markdownOptions);
-  return [content, transformedContent];
-};
-
-test('transform nothing', () => {
-  const doc1 = path.join(versionCurrent.contentPath, 'doc1.md');
-  const [content, transformedContent] = transform(doc1);
-  expect(transformedContent).toMatchSnapshot();
-  expect(content).toEqual(transformedContent);
-});
-
-test('transform to correct links', () => {
-  const doc2 = path.join(versionCurrent.contentPath, 'doc2.md');
-  const [content, transformedContent] = transform(doc2);
-  expect(transformedContent).toMatchSnapshot();
-  expect(transformedContent).toContain('](/docs/doc1');
-  expect(transformedContent).toContain('](/docs/doc2');
-  expect(transformedContent).toContain('](/docs/subdir/doc3');
-  expect(transformedContent).toContain('](/fr/doc-localized');
-  expect(transformedContent).not.toContain('](doc1.md)');
-  expect(transformedContent).not.toContain('](./doc2.md)');
-  expect(transformedContent).not.toContain('](subdir/doc3.md)');
-  expect(transformedContent).not.toContain('](/doc-localized');
-  expect(content).not.toEqual(transformedContent);
-});
-
-test('transform relative links', () => {
-  const doc3 = path.join(versionCurrent.contentPath, 'subdir', 'doc3.md');
-
-  const [content, transformedContent] = transform(doc3);
-  expect(transformedContent).toMatchSnapshot();
-  expect(transformedContent).toContain('](/docs/doc2');
-  expect(transformedContent).not.toContain('](../doc2.md)');
-  expect(content).not.toEqual(transformedContent);
-});
-
-test('transforms reference links', () => {
-  const doc4 = path.join(versionCurrent.contentPath, 'doc4.md');
-  const [content, transformedContent] = transform(doc4);
-  expect(transformedContent).toMatchSnapshot();
-  expect(transformedContent).toContain('[doc1]: /docs/doc1');
-  expect(transformedContent).toContain('[doc2]: /docs/doc2');
-  expect(transformedContent).not.toContain('[doc1]: doc1.md');
-  expect(transformedContent).not.toContain('[doc2]: ./doc2.md');
-  expect(content).not.toEqual(transformedContent);
-});
-
-test('report broken markdown links', () => {
-  const doc5 = path.join(versionCurrent.contentPath, 'doc5.md');
-  const onBrokenMarkdownLink = jest.fn();
-  const [content, transformedContent] = transform(doc5, {
-    onBrokenMarkdownLink,
-  });
-  expect(transformedContent).toEqual(content);
-  expect(onBrokenMarkdownLink).toHaveBeenCalledTimes(4);
-  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(1, {
-    filePath: doc5,
-    link: 'docNotExist1.md',
-    contentPaths: versionCurrent,
-  } as BrokenMarkdownLink);
-  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(2, {
-    filePath: doc5,
-    link: './docNotExist2.mdx',
-    contentPaths: versionCurrent,
-  } as BrokenMarkdownLink);
-  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(3, {
-    filePath: doc5,
-    link: '../docNotExist3.mdx',
-    contentPaths: versionCurrent,
-  } as BrokenMarkdownLink);
-  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(4, {
-    filePath: doc5,
-    link: './subdir/docNotExist4.md',
-    contentPaths: versionCurrent,
-  } as BrokenMarkdownLink);
-});
-
-test('transforms absolute links in versioned docs', () => {
-  const doc2 = path.join(version100.contentPath, 'doc2.md');
-  const [content, transformedContent] = transform(doc2);
-  expect(transformedContent).toMatchSnapshot();
-  expect(transformedContent).toContain('](/docs/1.0.0/subdir/doc1');
-  expect(transformedContent).toContain('](/docs/1.0.0/doc2#existing-docs');
-  expect(transformedContent).not.toContain('](subdir/doc1.md)');
-  expect(transformedContent).not.toContain('](doc2.md#existing-docs)');
-  expect(content).not.toEqual(transformedContent);
-});
-
-test('transforms relative links in versioned docs', () => {
-  const doc1 = path.join(version100.contentPath, 'subdir', 'doc1.md');
-  const [content, transformedContent] = transform(doc1);
-  expect(transformedContent).toMatchSnapshot();
-  expect(transformedContent).toContain('](/docs/1.0.0/doc2');
-  expect(transformedContent).not.toContain('](../doc2.md)');
-  expect(content).not.toEqual(transformedContent);
-});

package/src/sidebarItemsGenerator.ts

@@ -1,315 +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 {
-  SidebarItem,
-  SidebarItemDoc,
-  SidebarItemCategory,
-  SidebarItemsGenerator,
-  SidebarItemsGeneratorDoc,
-} from './types';
-import {sortBy, take, last, orderBy} from 'lodash';
-import {addTrailingSlash, posixPath} from '@docusaurus/utils';
-import {Joi} from '@docusaurus/utils-validation';
-import chalk from 'chalk';
-import path from 'path';
-import fs from 'fs-extra';
-import Yaml from 'js-yaml';
-
-const BreadcrumbSeparator = '/';
-
-export const CategoryMetadataFilenameBase = '_category_';
-export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
-
-export type CategoryMetadatasFile = {
-  label?: string;
-  position?: number;
-  collapsed?: boolean;
-  collapsible?: boolean;
-
-  // TODO should we allow "items" here? how would this work? would an "autogenerated" type be allowed?
-  // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
-  // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
-};
-
-type WithPosition = {position?: number};
-type SidebarItemWithPosition = SidebarItem & WithPosition;
-
-const CategoryMetadatasFileSchema = Joi.object<CategoryMetadatasFile>({
-  label: Joi.string(),
-  position: Joi.number(),
-  collapsed: Joi.boolean(),
-  collapsible: Joi.boolean(),
-});
-
-// TODO I now believe we should read all the category metadata files ahead of time: we may need this metadata to customize docs metadata
-// Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
-// TODO later if there is `CategoryFolder/index.md`, we may want to read the metadata as yaml on it
-// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadatasFile(
-  categoryDirPath: string,
-): Promise<CategoryMetadatasFile | null> {
-  function validateCategoryMetadataFile(
-    content: unknown,
-  ): CategoryMetadatasFile {
-    return Joi.attempt(content, CategoryMetadatasFileSchema);
-  }
-
-  async function tryReadFile(
-    fileNameWithExtension: string,
-    parse: (content: string) => unknown,
-  ): Promise<CategoryMetadatasFile | null> {
-    // Simpler to use only posix paths for mocking file metadatas in tests
-    const filePath = posixPath(
-      path.join(categoryDirPath, fileNameWithExtension),
-    );
-    if (await fs.pathExists(filePath)) {
-      const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
-      const unsafeContent: unknown = parse(contentString);
-      try {
-        return validateCategoryMetadataFile(unsafeContent);
-      } catch (e) {
-        console.error(
-          chalk.red(
-            `The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`,
-          ),
-        );
-        throw e;
-      }
-    }
-    return null;
-  }
-
-  return (
-    (await tryReadFile(`${CategoryMetadataFilenameBase}.json`, JSON.parse)) ??
-    (await tryReadFile(`${CategoryMetadataFilenameBase}.yml`, Yaml.load)) ??
-    // eslint-disable-next-line no-return-await
-    (await tryReadFile(`${CategoryMetadataFilenameBase}.yaml`, Yaml.load))
-  );
-}
-
-// [...parents, tail]
-function parseBreadcrumb(
-  breadcrumb: string[],
-): {parents: string[]; tail: string} {
-  return {
-    parents: take(breadcrumb, breadcrumb.length - 1),
-    tail: last(breadcrumb)!,
-  };
-}
-
-// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async function defaultSidebarItemsGenerator({
-  item,
-  docs: allDocs,
-  version,
-  numberPrefixParser,
-  options,
-}) {
-  // Doc at the root of the autogenerated sidebar dir
-  function isRootDoc(doc: SidebarItemsGeneratorDoc) {
-    return doc.sourceDirName === item.dirName;
-  }
-
-  // Doc inside a subfolder of the autogenerated sidebar dir
-  function isCategoryDoc(doc: SidebarItemsGeneratorDoc) {
-    if (isRootDoc(doc)) {
-      return false;
-    }
-
-    return (
-      // autogen dir is . and doc is in subfolder
-      item.dirName === '.' ||
-      // autogen dir is not . and doc is in subfolder
-      // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
-      doc.sourceDirName.startsWith(addTrailingSlash(item.dirName))
-    );
-  }
-
-  function isInAutogeneratedDir(doc: SidebarItemsGeneratorDoc) {
-    return isRootDoc(doc) || isCategoryDoc(doc);
-  }
-
-  // autogenDir=a/b and docDir=a/b/c/d => returns c/d
-  // autogenDir=a/b and docDir=a/b => returns .
-  function getDocDirRelativeToAutogenDir(
-    doc: SidebarItemsGeneratorDoc,
-  ): string {
-    if (!isInAutogeneratedDir(doc)) {
-      throw new Error(
-        'getDocDirRelativeToAutogenDir() can only be called for subdocs of the sidebar autogen dir.',
-      );
-    }
-    // Is there a node API to compare 2 relative paths more easily?
-    // path.relative() does not give good results
-    if (item.dirName === '.') {
-      return doc.sourceDirName;
-    } else if (item.dirName === doc.sourceDirName) {
-      return '.';
-    } else {
-      return doc.sourceDirName.replace(addTrailingSlash(item.dirName), '');
-    }
-  }
-
-  // Get only docs in the autogen dir
-  // Sort by folder+filename at once
-  const docs = sortBy(allDocs.filter(isInAutogeneratedDir), (d) => d.source);
-
-  if (docs.length === 0) {
-    console.warn(
-      chalk.yellow(
-        `No docs found in dir ${item.dirName}: can't auto-generate a sidebar.`,
-      ),
-    );
-  }
-
-  function createDocSidebarItem(
-    doc: SidebarItemsGeneratorDoc,
-  ): SidebarItemDoc & WithPosition {
-    return {
-      type: 'doc',
-      id: doc.id,
-      ...(doc.frontMatter.sidebar_label && {
-        label: doc.frontMatter.sidebar_label,
-      }),
-      ...(typeof doc.sidebarPosition !== 'undefined' && {
-        position: doc.sidebarPosition,
-      }),
-    };
-  }
-
-  async function createCategorySidebarItem({
-    breadcrumb,
-  }: {
-    breadcrumb: string[];
-  }): Promise<SidebarItemCategory & WithPosition> {
-    const categoryDirPath = path.join(
-      version.contentPath,
-      item.dirName, // fix https://github.com/facebook/docusaurus/issues/4638
-      breadcrumb.join(BreadcrumbSeparator),
-    );
-
-    const categoryMetadatas = await readCategoryMetadatasFile(categoryDirPath);
-
-    const {tail} = parseBreadcrumb(breadcrumb);
-
-    const {filename, numberPrefix} = numberPrefixParser(tail);
-
-    const position = categoryMetadatas?.position ?? numberPrefix;
-
-    const collapsible =
-      categoryMetadatas?.collapsible ?? options.sidebarCollapsible;
-    const collapsed = categoryMetadatas?.collapsed ?? options.sidebarCollapsed;
-
-    return {
-      type: 'category',
-      label: categoryMetadatas?.label ?? filename,
-      items: [],
-      collapsed,
-      collapsible,
-      ...(typeof position !== 'undefined' && {position}),
-    };
-  }
-
-  // Not sure how to simplify this algorithm :/
-  async function autogenerateSidebarItems(): Promise<
-    SidebarItemWithPosition[]
-  > {
-    const sidebarItems: SidebarItem[] = []; // mutable result
-
-    const categoriesByBreadcrumb: Record<string, SidebarItemCategory> = {}; // mutable cache of categories already created
-
-    async function getOrCreateCategoriesForBreadcrumb(
-      breadcrumb: string[],
-    ): Promise<SidebarItemCategory | null> {
-      if (breadcrumb.length === 0) {
-        return null;
-      }
-      const {parents} = parseBreadcrumb(breadcrumb);
-      const parentCategory = await getOrCreateCategoriesForBreadcrumb(parents);
-      const existingCategory =
-        categoriesByBreadcrumb[breadcrumb.join(BreadcrumbSeparator)];
-
-      if (existingCategory) {
-        return existingCategory;
-      } else {
-        const newCategory = await createCategorySidebarItem({
-          breadcrumb,
-        });
-        if (parentCategory) {
-          parentCategory.items.push(newCategory);
-        } else {
-          sidebarItems.push(newCategory);
-        }
-        categoriesByBreadcrumb[
-          breadcrumb.join(BreadcrumbSeparator)
-        ] = newCategory;
-        return newCategory;
-      }
-    }
-
-    // Get the category breadcrumb of a doc (relative to the dir of the autogenerated sidebar item)
-    function getRelativeBreadcrumb(doc: SidebarItemsGeneratorDoc): string[] {
-      const relativeDirPath = getDocDirRelativeToAutogenDir(doc);
-      if (relativeDirPath === '.') {
-        return [];
-      } else {
-        return relativeDirPath.split(BreadcrumbSeparator);
-      }
-    }
-
-    async function handleDocItem(doc: SidebarItemsGeneratorDoc): Promise<void> {
-      const breadcrumb = getRelativeBreadcrumb(doc);
-      const category = await getOrCreateCategoriesForBreadcrumb(breadcrumb);
-
-      const docSidebarItem = createDocSidebarItem(doc);
-      if (category) {
-        category.items.push(docSidebarItem);
-      } else {
-        sidebarItems.push(docSidebarItem);
-      }
-    }
-
-    // async process made sequential on purpose! order matters
-    // eslint-disable-next-line no-restricted-syntax
-    for (const doc of docs) {
-      // eslint-disable-next-line no-await-in-loop
-      await handleDocItem(doc);
-    }
-
-    return sidebarItems;
-  }
-
-  const sidebarItems = await autogenerateSidebarItems();
-
-  return sortSidebarItems(sidebarItems);
-};
-
-// Recursively sort the categories/docs + remove the "position" attribute from final output
-// Note: the "position" is only used to sort "inside" a sidebar slice
-// It is not used to sort across multiple consecutive sidebar slices (ie a whole Category composed of multiple autogenerated items)
-function sortSidebarItems(
-  sidebarItems: SidebarItemWithPosition[],
-): SidebarItem[] {
-  const processedSidebarItems = sidebarItems.map((item) => {
-    if (item.type === 'category') {
-      return {
-        ...item,
-        items: sortSidebarItems(item.items),
-      };
-    }
-    return item;
-  });
-
-  const sortedSidebarItems = orderBy(
-    processedSidebarItems,
-    (item) => item.position,
-    ['asc'],
-  );
-
-  return sortedSidebarItems.map(({position: _removed, ...item}) => item);
-}