@seqera/docusaurus-theme-seqera 1.0.0

package/src/theme/DocCard/index.tsx

@@ -0,0 +1,133 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import {
+  useDocById,
+  findFirstSidebarItemLink,
+} from '@docusaurus/plugin-content-docs/client';
+import {usePluralForm} from '@docusaurus/theme-common';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
+
+import type {Props} from '@theme/DocCard';
+import Heading from '@theme/Heading';
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from '@docusaurus/plugin-content-docs';
+
+import styles from './styles.module.css';
+
+function useCategoryItemsPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          message: '1 item|{count} items',
+          id: 'theme.docs.DocCard.categoryDescription.plurals',
+          description:
+            'The default description for a category card in the generated index about how many items this category includes',
+        },
+        {count},
+      ),
+    );
+}
+
+function CardContainer({
+  className,
+  href,
+  children,
+}: {
+  className?: string;
+  href: string;
+  children: ReactNode;
+}): ReactNode {
+  return (
+    <Link
+      href={href}
+      className={clsx('card padding--lg', styles.cardContainer, className)}>
+      {children}
+    </Link>
+  );
+}
+
+function CardLayout({
+  className,
+  href,
+  icon,
+  title,
+  description,
+}: {
+  className?: string;
+  href: string;
+  icon: ReactNode;
+  title: string;
+  description?: string;
+}): ReactNode {
+  return (
+    <CardContainer href={href} className={className}>
+      <Heading
+        as="h2"
+        className={clsx('text--truncate', styles.cardTitle)}
+        title={title}>
+        {icon} {title}
+      </Heading>
+      {description && (
+        <p
+          className={clsx('text--truncate', styles.cardDescription)}
+          title={description}>
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}: {item: PropSidebarItemCategory}): ReactNode {
+  const href = findFirstSidebarItemLink(item);
+  const categoryItemsPlural = useCategoryItemsPlural();
+
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+
+  return (
+    <CardLayout
+      className={item.className}
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={item.description ?? categoryItemsPlural(item.items.length)}
+    />
+  );
+}
+
+function CardLink({item}: {item: PropSidebarItemLink}): ReactNode {
+  const icon = isInternalUrl(item.href) ? '📄️' : '🔗';
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      className={item.className}
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+export default function DocCard({item}: Props): ReactNode {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

package/src/theme/DocCard/styles.module.css

@@ -0,0 +1,29 @@
+
+
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}

package/src/theme/DocCardList/index.tsx

@@ -0,0 +1,43 @@
+
+
+import React, {type ComponentProps, type ReactNode} from 'react';
+import clsx from 'clsx';
+import {
+  useCurrentSidebarSiblings,
+  filterDocCardListItems,
+} from '@docusaurus/plugin-content-docs/client';
+import DocCard from '@theme/DocCard';
+import type {Props} from '@theme/DocCardList';
+import styles from './styles.module.css';
+
+function DocCardListForCurrentSidebarCategory({className}: Props) {
+  const items = useCurrentSidebarSiblings();
+  return <DocCardList items={items} className={className} />;
+}
+
+function DocCardListItem({
+  item,
+}: {
+  item: ComponentProps<typeof DocCard>['item'];
+}) {
+  return (
+    <article className={clsx(styles.docCardListItem, 'col col--6')}>
+      <DocCard item={item} />
+    </article>
+  );
+}
+
+export default function DocCardList(props: Props): ReactNode {
+  const {items, className} = props;
+  if (!items) {
+    return <DocCardListForCurrentSidebarCategory {...props} />;
+  }
+  const filteredItems = filterDocCardListItems(items);
+  return (
+    <section className={clsx('row', className)}>
+      {filteredItems.map((item, index) => (
+        <DocCardListItem key={index} item={item} />
+      ))}
+    </section>
+  );
+}

package/src/theme/DocCardList/styles.module.css

@@ -0,0 +1,9 @@
+
+
+.docCardListItem {
+  margin-bottom: 2rem;
+}
+
+.docCardListItem > * {
+  height: 100%;
+}

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -0,0 +1,68 @@
+
+
+import React, {type ReactNode} from 'react';
+import {PageMetadata} from '@docusaurus/theme-common';
+import {useCurrentSidebarCategory} from '@docusaurus/plugin-content-docs/client';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import DocCardList from '@theme/DocCardList';
+import DocPaginator from '@theme/DocPaginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import Heading from '@theme/Heading';
+import type {Props} from '@theme/DocCategoryGeneratedIndexPage';
+
+import styles from './styles.module.css';
+
+function DocCategoryGeneratedIndexPageMetadata({
+  categoryGeneratedIndex,
+}: Props): ReactNode {
+  return (
+    <PageMetadata
+      title={categoryGeneratedIndex.title}
+      description={categoryGeneratedIndex.description}
+      keywords={categoryGeneratedIndex.keywords}
+      // TODO `require` this?
+      image={useBaseUrl(categoryGeneratedIndex.image)}
+    />
+  );
+}
+
+function DocCategoryGeneratedIndexPageContent({
+  categoryGeneratedIndex,
+}: Props): ReactNode {
+  const category = useCurrentSidebarCategory();
+  return (
+    <div className={styles.generatedIndexPage}>
+      <DocVersionBanner />
+      <DocBreadcrumbs />
+      <DocVersionBadge />
+      <header>
+        <Heading as="h1" className={styles.title}>
+          {categoryGeneratedIndex.title}
+        </Heading>
+        {categoryGeneratedIndex.description && (
+          <p>{categoryGeneratedIndex.description}</p>
+        )}
+      </header>
+      <article className="margin-top--lg">
+        <DocCardList items={category.items} className={styles.list} />
+      </article>
+      <footer className="margin-top--md">
+        <DocPaginator
+          previous={categoryGeneratedIndex.navigation.previous}
+          next={categoryGeneratedIndex.navigation.next}
+        />
+      </footer>
+    </div>
+  );
+}
+
+export default function DocCategoryGeneratedIndexPage(props: Props): ReactNode {
+  return (
+    <>
+      <DocCategoryGeneratedIndexPageMetadata {...props} />
+      <DocCategoryGeneratedIndexPageContent {...props} />
+    </>
+  );
+}

package/src/theme/DocCategoryGeneratedIndexPage/styles.module.css

@@ -0,0 +1,13 @@
+
+
+@media (min-width: 997px) {
+  .generatedIndexPage {
+    max-width: 75% !important;
+  }
+}
+
+/* Duplicated from .markdown h1 */
+.title {
+  --ifm-h1-font-size: 3rem;
+  margin-bottom: calc(1.25 * var(--ifm-leading));
+}

package/src/theme/DocItem/Content/index.tsx

@@ -0,0 +1,43 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+import type {Props} from '@theme/DocItem/Content';
+
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle(): string | null {
+  const {metadata, frontMatter, contentTitle} = useDoc();
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === 'undefined';
+  if (!shouldRender) {
+    return null;
+  }
+  return metadata.title;
+}
+
+export default function DocItemContent({children}: Props): ReactNode {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

package/src/theme/DocItem/Footer/index.tsx

@@ -0,0 +1,51 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import TagsListInline from '@theme/TagsListInline';
+
+import EditMetaRow from '@theme/EditMetaRow';
+
+export default function DocItemFooter(): ReactNode {
+  const {metadata} = useDoc();
+  const {editUrl, lastUpdatedAt, lastUpdatedBy, tags} = metadata;
+
+  const canDisplayTagsRow = tags.length > 0;
+  const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+
+  const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow;
+
+  if (!canDisplayFooter) {
+    return null;
+  }
+
+  return (
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}>
+      {canDisplayTagsRow && (
+        <div
+          className={clsx(
+            'row margin-top--sm',
+            ThemeClassNames.docs.docFooterTagsRow,
+          )}>
+          <div className="col">
+            <TagsListInline tags={tags} />
+          </div>
+        </div>
+      )}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          className={clsx(
+            'margin-top--sm',
+            ThemeClassNames.docs.docFooterEditMetaRow,
+          )}
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+        />
+      )}
+    </footer>
+  );
+}

package/src/theme/DocItem/Layout/index.tsx

@@ -0,0 +1,66 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import DocItemPaginator from '@theme/DocItem/Paginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocItemFooter from '@theme/DocItem/Footer';
+import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
+import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
+import DocItemContent from '@theme/DocItem/Content';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import ContentVisibility from '@theme/ContentVisibility';
+import type {Props} from '@theme/DocItem/Layout';
+
+import styles from './styles.module.css';
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const {frontMatter, toc} = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({children}: Props): ReactNode {
+  const docTOC = useDocTOC();
+  const {metadata} = useDoc();
+  return (
+    <div className="row">
+      <div className={clsx('prose__wrapper mx-auto px-4', !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article className="max-w-3xl">
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">{docTOC.desktop}</div>}
+    </div>
+  );
+}

package/src/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,12 @@
+
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+}

package/src/theme/DocItem/Metadata/index.tsx

@@ -0,0 +1,17 @@
+
+
+import React, {type ReactNode} from 'react';
+import {PageMetadata} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+
+export default function DocItemMetadata(): ReactNode {
+  const {metadata, frontMatter, assets} = useDoc();
+  return (
+    <PageMetadata
+      title={metadata.title}
+      description={metadata.description}
+      keywords={frontMatter.keywords}
+      image={assets.image ?? frontMatter.image}
+    />
+  );
+}

package/src/theme/DocItem/Paginator/index.tsx

@@ -0,0 +1,20 @@
+
+
+import React, {type ReactNode} from 'react';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import DocPaginator from '@theme/DocPaginator';
+
+/**
+ * This extra component is needed, because <DocPaginator> should remain generic.
+ * DocPaginator is used in non-docs contexts too: generated-index pages...
+ */
+export default function DocItemPaginator(): ReactNode {
+  const {metadata} = useDoc();
+  return (
+    <DocPaginator
+      className="docusaurus-mt-lg"
+      previous={metadata.previous}
+      next={metadata.next}
+    />
+  );
+}

package/src/theme/DocItem/TOC/Desktop/index.tsx

@@ -0,0 +1,19 @@
+
+
+import React, {type ReactNode} from 'react';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+
+import TOC from '@theme/TOC';
+
+export default function DocItemTOCDesktop(): ReactNode {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOC
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={ThemeClassNames.docs.docTocDesktop}
+    />
+  );
+}

package/src/theme/DocItem/TOC/Mobile/index.tsx

@@ -0,0 +1,22 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+
+import TOCCollapsible from '@theme/TOCCollapsible';
+
+import styles from './styles.module.css';
+
+export default function DocItemTOCMobile(): ReactNode {
+  const {toc, frontMatter} = useDoc();
+  return (
+    <TOCCollapsible
+      toc={toc}
+      minHeadingLevel={frontMatter.toc_min_heading_level}
+      maxHeadingLevel={frontMatter.toc_max_heading_level}
+      className={clsx(ThemeClassNames.docs.docTocMobile, styles.tocMobile)}
+    />
+  );
+}

package/src/theme/DocItem/TOC/Mobile/styles.module.css

@@ -0,0 +1,26 @@
+
+
+@media (min-width: 997px) {
+  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+  .tocMobile {
+    display: none;
+  }
+}
+
+@media print {
+  .tocMobile {
+    display: none;
+  }
+}
+
+/* Use :global() for non-module classes */
+.tocMobile ul {
+  list-style: none;
+  padding-left: 0;
+  margin: 0;
+}
+
+.tocMobile :global(.undefined) {
+  border-left: 1px solid var(--color-gray-400);
+}
+

package/src/theme/DocItem/index.tsx

@@ -0,0 +1,23 @@
+
+
+import React, {type ReactNode} from 'react';
+import {HtmlClassNameProvider} from '@docusaurus/theme-common';
+import {DocProvider} from '@docusaurus/plugin-content-docs/client';
+import DocItemMetadata from '@theme/DocItem/Metadata';
+import DocItemLayout from '@theme/DocItem/Layout';
+import type {Props} from '@theme/DocItem';
+
+export default function DocItem(props: Props): ReactNode {
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
+  const MDXComponent = props.content;
+  return (
+    <DocProvider content={props.content}>
+      <HtmlClassNameProvider className={docHtmlClassName}>
+        <DocItemMetadata />
+        <DocItemLayout>
+          <MDXComponent />
+        </DocItemLayout>
+      </HtmlClassNameProvider>
+    </DocProvider>
+  );
+}

package/src/theme/DocPaginator/index.tsx

@@ -0,0 +1,46 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import Translate, {translate} from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
+import type {Props} from '@theme/DocPaginator';
+
+export default function DocPaginator(props: Props): ReactNode {
+  const {className, previous, next} = props;
+  return (
+    <nav
+      className={clsx(className, 'pagination-nav')}
+      aria-label={translate({
+        id: 'theme.docs.paginator.navAriaLabel',
+        message: 'Docs pages',
+        description: 'The ARIA label for the docs pagination',
+      })}>
+      {previous && (
+        <PaginatorNavLink
+          {...previous}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.previous"
+              description="The label used to navigate to the previous doc">
+              Previous
+            </Translate>
+          }
+        />
+      )}
+      {next && (
+        <PaginatorNavLink
+          {...next}
+          subLabel={
+            <Translate
+              id="theme.docs.paginator.next"
+              description="The label used to navigate to the next doc">
+              Next
+            </Translate>
+          }
+          isNext
+        />
+      )}
+    </nav>
+  );
+}

package/src/theme/DocRoot/Layout/Main/index.tsx

@@ -0,0 +1,31 @@
+
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {useDocsSidebar} from '@docusaurus/plugin-content-docs/client';
+import type {Props} from '@theme/DocRoot/Layout/Main';
+
+import styles from './styles.module.css';
+
+export default function DocRootLayoutMain({
+  hiddenSidebarContainer,
+  children,
+}: Props): ReactNode {
+  const sidebar = useDocsSidebar();
+  return (
+    <main
+      className={clsx(
+        styles.docMainContainer,
+        (hiddenSidebarContainer || !sidebar) && styles.docMainContainerEnhanced,
+      )}>
+      <div
+        className={clsx(
+          'container padding-top--md padding-bottom--lg',
+          styles.docItemWrapper,
+          hiddenSidebarContainer && styles.docItemWrapperEnhanced,
+        )}>
+        {children}
+      </div>
+    </main>
+  );
+}