@docusaurus/theme-common 3.3.2 → 3.5.0

package/src/utils/docsUtils.tsx

@@ -1,418 +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 {useMemo} from 'react';
-import {matchPath, useLocation} from '@docusaurus/router';
-import renderRoutes from '@docusaurus/renderRoutes';
-import {
-  useAllDocsData,
-  useActivePlugin,
-  useActiveDocContext,
-  useLatestVersion,
-  type GlobalVersion,
-  type GlobalSidebar,
-  type GlobalDoc,
-} from '@docusaurus/plugin-content-docs/client';
-import type {Props as DocRootProps} from '@theme/DocRoot';
-import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
-import {useDocsVersion} from '../contexts/docsVersion';
-import {useDocsSidebar} from '../contexts/docsSidebar';
-import {uniq} from './jsUtils';
-import {isSamePath} from './routesUtils';
-import type {
-  PropSidebar,
-  PropSidebarItem,
-  PropSidebarItemCategory,
-  PropVersionDoc,
-  PropSidebarBreadcrumbsItem,
-} from '@docusaurus/plugin-content-docs';
-
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;
-
-/**
- * A null-safe way to access a doc's data by ID in the active version.
- */
-export function useDocById(id: string): PropVersionDoc;
-/**
- * A null-safe way to access a doc's data by ID in the active version.
- */
-export function useDocById(id: string | undefined): PropVersionDoc | undefined;
-export function useDocById(id: string | undefined): PropVersionDoc | undefined {
-  const version = useDocsVersion();
-  if (!id) {
-    return undefined;
-  }
-  const doc = version.docs[id];
-  if (!doc) {
-    throw new Error(`no version doc found by id=${id}`);
-  }
-  return doc;
-}
-
-/**
- * Pure function, similar to `Array#find`, but works on the sidebar tree.
- */
-export function findSidebarCategory(
-  sidebar: PropSidebar,
-  predicate: (category: PropSidebarItemCategory) => boolean,
-): PropSidebarItemCategory | undefined {
-  for (const item of sidebar) {
-    if (item.type === 'category') {
-      if (predicate(item)) {
-        return item;
-      }
-      const subItem = findSidebarCategory(item.items, predicate);
-      if (subItem) {
-        return subItem;
-      }
-    }
-  }
-  return undefined;
-}
-
-/**
- * Best effort to assign a link to a sidebar category. If the category doesn't
- * have a link itself, we link to the first sub item with a link.
- */
-export function findFirstSidebarItemCategoryLink(
-  item: PropSidebarItemCategory,
-): string | undefined {
-  if (item.href && !item.linkUnlisted) {
-    return item.href;
-  }
-
-  for (const subItem of item.items) {
-    const link = findFirstSidebarItemLink(subItem);
-    if (link) {
-      return link;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Best effort to assign a link to a sidebar item.
- */
-export function findFirstSidebarItemLink(
-  item: PropSidebarItem,
-): string | undefined {
-  if (item.type === 'link' && !item.unlisted) {
-    return item.href;
-  }
-  if (item.type === 'category') {
-    return findFirstSidebarItemCategoryLink(item);
-  }
-  // Other items types, like "html"
-  return undefined;
-}
-
-/**
- * Gets the category associated with the current location. Should only be used
- * on category index pages.
- */
-export function useCurrentSidebarCategory(): PropSidebarItemCategory {
-  const {pathname} = useLocation();
-  const sidebar = useDocsSidebar();
-  if (!sidebar) {
-    throw new Error('Unexpected: cant find current sidebar in context');
-  }
-  const categoryBreadcrumbs = getSidebarBreadcrumbs({
-    sidebarItems: sidebar.items,
-    pathname,
-    onlyCategories: true,
-  });
-  const deepestCategory = categoryBreadcrumbs.slice(-1)[0];
-  if (!deepestCategory) {
-    throw new Error(
-      `${pathname} is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.`,
-    );
-  }
-  return deepestCategory;
-}
-
-const isActive = (testedPath: string | undefined, activePath: string) =>
-  typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
-const containsActiveSidebarItem = (
-  items: PropSidebarItem[],
-  activePath: string,
-) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
-
-/**
- * Checks if a sidebar item should be active, based on the active path.
- */
-export function isActiveSidebarItem(
-  item: PropSidebarItem,
-  activePath: string,
-): boolean {
-  if (item.type === 'link') {
-    return isActive(item.href, activePath);
-  }
-
-  if (item.type === 'category') {
-    return (
-      isActive(item.href, activePath) ||
-      containsActiveSidebarItem(item.items, activePath)
-    );
-  }
-
-  return false;
-}
-
-export function isVisibleSidebarItem(
-  item: PropSidebarItem,
-  activePath: string,
-): boolean {
-  switch (item.type) {
-    case 'category':
-      return (
-        isActiveSidebarItem(item, activePath) ||
-        item.items.some((subItem) => isVisibleSidebarItem(subItem, activePath))
-      );
-    case 'link':
-      // An unlisted item remains visible if it is active
-      return !item.unlisted || isActiveSidebarItem(item, activePath);
-    default:
-      return true;
-  }
-}
-
-export function useVisibleSidebarItems(
-  items: readonly PropSidebarItem[],
-  activePath: string,
-): PropSidebarItem[] {
-  return useMemo(
-    () => items.filter((item) => isVisibleSidebarItem(item, activePath)),
-    [items, activePath],
-  );
-}
-
-function getSidebarBreadcrumbs(param: {
-  sidebarItems: PropSidebar;
-  pathname: string;
-  onlyCategories: true;
-}): PropSidebarItemCategory[];
-
-function getSidebarBreadcrumbs(param: {
-  sidebarItems: PropSidebar;
-  pathname: string;
-}): PropSidebarBreadcrumbsItem[];
-
-/**
- * Get the sidebar the breadcrumbs for a given pathname
- * Ordered from top to bottom
- */
-function getSidebarBreadcrumbs({
-  sidebarItems,
-  pathname,
-  onlyCategories = false,
-}: {
-  sidebarItems: PropSidebar;
-  pathname: string;
-  onlyCategories?: boolean;
-}): PropSidebarBreadcrumbsItem[] {
-  const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
-
-  function extract(items: PropSidebarItem[]) {
-    for (const item of items) {
-      if (
-        (item.type === 'category' &&
-          (isSamePath(item.href, pathname) || extract(item.items))) ||
-        (item.type === 'link' && isSamePath(item.href, pathname))
-      ) {
-        const filtered = onlyCategories && item.type !== 'category';
-        if (!filtered) {
-          breadcrumbs.unshift(item);
-        }
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  extract(sidebarItems);
-
-  return breadcrumbs;
-}
-
-/**
- * Gets the breadcrumbs of the current doc page, based on its sidebar location.
- * Returns `null` if there's no sidebar or breadcrumbs are disabled.
- */
-export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
-  const sidebar = useDocsSidebar();
-  const {pathname} = useLocation();
-  const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
-  if (breadcrumbsOption === false || !sidebar) {
-    return null;
-  }
-  return getSidebarBreadcrumbs({sidebarItems: sidebar.items, pathname});
-}
-
-/**
- * "Version candidates" are mostly useful for the layout components, which must
- * be able to work on all pages. For example, if a user has `{ type: "doc",
- * docId: "intro" }` as a navbar item, which version does that refer to? We
- * believe that it could refer to at most three version candidates:
- *
- * 1. The **active version**, the one that the user is currently browsing. See
- * {@link useActiveDocContext}.
- * 2. The **preferred version**, the one that the user last visited. See
- * {@link useDocsPreferredVersion}.
- * 3. The **latest version**, the "default". See {@link useLatestVersion}.
- *
- * @param docsPluginId The plugin ID to get versions from.
- * @returns An array of 1~3 versions with priorities defined above, guaranteed
- * to be unique and non-sparse. Will be memoized, hence stable for deps array.
- */
-export function useDocsVersionCandidates(
-  docsPluginId?: string,
-): [GlobalVersion, ...GlobalVersion[]] {
-  const {activeVersion} = useActiveDocContext(docsPluginId);
-  const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
-  const latestVersion = useLatestVersion(docsPluginId);
-  return useMemo(
-    () =>
-      uniq(
-        [activeVersion, preferredVersion, latestVersion].filter(Boolean),
-      ) as [GlobalVersion, ...GlobalVersion[]],
-    [activeVersion, preferredVersion, latestVersion],
-  );
-}
-
-/**
- * The layout components, like navbar items, must be able to work on all pages,
- * even on non-doc ones where there's no version context, so a sidebar ID could
- * be ambiguous. This hook would always return a sidebar to be linked to. See
- * also {@link useDocsVersionCandidates} for how this selection is done.
- *
- * @throws This hook throws if a sidebar with said ID is not found.
- */
-export function useLayoutDocsSidebar(
-  sidebarId: string,
-  docsPluginId?: string,
-): GlobalSidebar {
-  const versions = useDocsVersionCandidates(docsPluginId);
-  return useMemo(() => {
-    const allSidebars = versions.flatMap((version) =>
-      version.sidebars ? Object.entries(version.sidebars) : [],
-    );
-    const sidebarEntry = allSidebars.find(
-      (sidebar) => sidebar[0] === sidebarId,
-    );
-    if (!sidebarEntry) {
-      throw new Error(
-        `Can't find any sidebar with id "${sidebarId}" in version${
-          versions.length > 1 ? 's' : ''
-        } ${versions.map((version) => version.name).join(', ')}".
-Available sidebar ids are:
-- ${allSidebars.map((entry) => entry[0]).join('\n- ')}`,
-      );
-    }
-    return sidebarEntry[1];
-  }, [sidebarId, versions]);
-}
-
-/**
- * The layout components, like navbar items, must be able to work on all pages,
- * even on non-doc ones where there's no version context, so a doc ID could be
- * ambiguous. This hook would always return a doc to be linked to. See also
- * {@link useDocsVersionCandidates} for how this selection is done.
- *
- * @throws This hook throws if a doc with said ID is not found.
- */
-export function useLayoutDoc(
-  docId: string,
-  docsPluginId?: string,
-): GlobalDoc | null {
-  const versions = useDocsVersionCandidates(docsPluginId);
-  return useMemo(() => {
-    const allDocs = versions.flatMap((version) => version.docs);
-    const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
-    if (!doc) {
-      const isDraft = versions
-        .flatMap((version) => version.draftIds)
-        .includes(docId);
-      // Drafts should be silently filtered instead of throwing
-      if (isDraft) {
-        return null;
-      }
-      throw new Error(
-        `Couldn't find any doc with id "${docId}" in version${
-          versions.length > 1 ? 's' : ''
-        } "${versions.map((version) => version.name).join(', ')}".
-Available doc ids are:
-- ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`,
-      );
-    }
-    return doc;
-  }, [docId, versions]);
-}
-
-// TODO later read version/route directly from context
-/**
- * The docs plugin creates nested routes, with the top-level route providing the
- * version metadata, and the subroutes creating individual doc pages. This hook
- * will match the current location against all known sub-routes.
- *
- * @param props The props received by `@theme/DocRoot`
- * @returns The data of the relevant document at the current location, or `null`
- * if no document associated with the current location can be found.
- */
-export function useDocRootMetadata({route}: DocRootProps): null | {
-  /** The element that should be rendered at the current location. */
-  docElement: JSX.Element;
-  /**
-   * The name of the sidebar associated with the current doc. `sidebarName` and
-   * `sidebarItems` correspond to the value of {@link useDocsSidebar}.
-   */
-  sidebarName: string | undefined;
-  /** The items of the sidebar associated with the current doc. */
-  sidebarItems: PropSidebar | undefined;
-} {
-  const location = useLocation();
-  const versionMetadata = useDocsVersion();
-  const docRoutes = route.routes!;
-  const currentDocRoute = docRoutes.find((docRoute) =>
-    matchPath(location.pathname, docRoute),
-  );
-  if (!currentDocRoute) {
-    return null;
-  }
-
-  // For now, the sidebarName is added as route config: not ideal!
-  const sidebarName = currentDocRoute.sidebar as string;
-
-  const sidebarItems = sidebarName
-    ? versionMetadata.docsSidebars[sidebarName]
-    : undefined;
-
-  const docElement = renderRoutes(docRoutes);
-
-  return {
-    docElement,
-    sidebarName,
-    sidebarItems,
-  };
-}
-
-/**
- * Filter items we don't want to display on the doc card list view
- * @param items
- */
-export function filterDocCardListItems(
-  items: PropSidebarItem[],
-): PropSidebarItem[] {
-  return items.filter((item) => {
-    const canHaveLink = item.type === 'category' || item.type === 'link';
-    if (canHaveLink) {
-      return !!findFirstSidebarItemLink(item);
-    }
-    return true;
-  });
-}

package/src/utils/structuredDataUtils.ts

@@ -1,177 +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 {useBaseUrlUtils, type BaseUrlUtils} from '@docusaurus/useBaseUrl';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useBlogMetadata} from '@docusaurus/plugin-content-blog/client';
-import type {Props as BlogListPageStructuredDataProps} from '@theme/BlogListPage/StructuredData';
-import {useBlogPost} from '../contexts/blogPost';
-import type {
-  Blog,
-  BlogPosting,
-  WithContext,
-  Person,
-  ImageObject,
-} from 'schema-dts';
-import type {
-  Author,
-  PropBlogPostContent,
-} from '@docusaurus/plugin-content-blog';
-import type {DocusaurusConfig} from '@docusaurus/types';
-
-const convertDate = (dateMs: number) => new Date(dateMs).toISOString();
-
-function getBlogPost(
-  blogPostContent: PropBlogPostContent,
-  siteConfig: DocusaurusConfig,
-  withBaseUrl: BaseUrlUtils['withBaseUrl'],
-): BlogPosting {
-  const {assets, frontMatter, metadata} = blogPostContent;
-  const {date, title, description, lastUpdatedAt} = metadata;
-
-  const image = assets.image ?? frontMatter.image;
-  const keywords = frontMatter.keywords ?? [];
-
-  const blogUrl = `${siteConfig.url}${metadata.permalink}`;
-
-  const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
-
-  return {
-    '@type': 'BlogPosting',
-    '@id': blogUrl,
-    mainEntityOfPage: blogUrl,
-    url: blogUrl,
-    headline: title,
-    name: title,
-    description,
-    datePublished: date,
-    ...(dateModified ? {dateModified} : {}),
-    ...getAuthor(metadata.authors),
-    ...getImage(image, withBaseUrl, title),
-    ...(keywords ? {keywords} : {}),
-  };
-}
-
-function getAuthor(authors: Author[]) {
-  const authorsStructuredData = authors.map(createPersonStructuredData);
-  return {
-    author:
-      authorsStructuredData.length === 1
-        ? authorsStructuredData[0]
-        : authorsStructuredData,
-  };
-}
-
-function getImage(
-  image: string | undefined,
-  withBaseUrl: BaseUrlUtils['withBaseUrl'],
-  title: string,
-) {
-  return image
-    ? {
-        image: createImageStructuredData({
-          imageUrl: withBaseUrl(image, {absolute: true}),
-          caption: `title image for the blog post: ${title}`,
-        }),
-      }
-    : {};
-}
-
-export function useBlogListPageStructuredData(
-  props: BlogListPageStructuredDataProps,
-): WithContext<Blog> {
-  const {siteConfig} = useDocusaurusContext();
-  const {withBaseUrl} = useBaseUrlUtils();
-
-  const {
-    metadata: {blogDescription, blogTitle, permalink},
-  } = props;
-
-  const url = `${siteConfig.url}${permalink}`;
-
-  // details on structured data support: https://schema.org/Blog
-  return {
-    '@context': 'https://schema.org',
-    '@type': 'Blog',
-    '@id': url,
-    mainEntityOfPage: url,
-    headline: blogTitle,
-    description: blogDescription,
-    blogPost: props.items.map((blogItem) =>
-      getBlogPost(blogItem.content, siteConfig, withBaseUrl),
-    ),
-  };
-}
-
-export function useBlogPostStructuredData(): WithContext<BlogPosting> {
-  const blogMetadata = useBlogMetadata();
-  const {assets, metadata} = useBlogPost();
-  const {siteConfig} = useDocusaurusContext();
-  const {withBaseUrl} = useBaseUrlUtils();
-
-  const {date, title, description, frontMatter, lastUpdatedAt} = metadata;
-
-  const image = assets.image ?? frontMatter.image;
-  const keywords = frontMatter.keywords ?? [];
-
-  const dateModified = lastUpdatedAt ? convertDate(lastUpdatedAt) : undefined;
-
-  const url = `${siteConfig.url}${metadata.permalink}`;
-
-  // details on structured data support: https://schema.org/BlogPosting
-  // BlogPosting is one of the structured data types that Google explicitly
-  // supports: https://developers.google.com/search/docs/appearance/structured-data/article#structured-data-type-definitions
-  return {
-    '@context': 'https://schema.org',
-    '@type': 'BlogPosting',
-    '@id': url,
-    mainEntityOfPage: url,
-    url,
-    headline: title,
-    name: title,
-    description,
-    datePublished: date,
-    ...(dateModified ? {dateModified} : {}),
-    ...getAuthor(metadata.authors),
-    ...getImage(image, withBaseUrl, title),
-    ...(keywords ? {keywords} : {}),
-    isPartOf: {
-      '@type': 'Blog',
-      '@id': `${siteConfig.url}${blogMetadata.blogBasePath}`,
-      name: blogMetadata.blogTitle,
-    },
-  };
-}
-
-/** @returns A {@link https://schema.org/Person} constructed from the {@link Author} */
-function createPersonStructuredData(author: Author): Person {
-  return {
-    '@type': 'Person',
-    ...(author.name ? {name: author.name} : {}),
-    ...(author.title ? {description: author.title} : {}),
-    ...(author.url ? {url: author.url} : {}),
-    ...(author.email ? {email: author.email} : {}),
-    ...(author.imageURL ? {image: author.imageURL} : {}),
-  };
-}
-
-/** @returns A {@link https://schema.org/ImageObject} */
-function createImageStructuredData({
-  imageUrl,
-  caption,
-}: {
-  imageUrl: string;
-  caption: string;
-}): ImageObject {
-  return {
-    '@type': 'ImageObject',
-    '@id': imageUrl,
-    url: imageUrl,
-    contentUrl: imageUrl,
-    caption,
-  };
-}