styling breadcrumbs and toc

docusaurus.config.js

@@ -219,6 +219,7 @@ module.exports = {
             require.resolve('./src/css/custom.css'),
             require.resolve('./src/css/font.css'),
             require.resolve('./src/css/types.css'),
+            require.resolve('./src/css/index.css'),
           ],
         },
       },

package.json

@@ -76,7 +76,8 @@
     "postcss": "^8.4.47",
     "prettier": "3.3.3",
     "tailwindcss": "^3.4.13",
-    "typescript": "^4.8.4"
+    "typescript": "^4.8.4",
+    "postcss-import": "^16.1.0"
   },
   "engines": {
     "npm": "please-use-yarn",

postcss.config.js

@@ -0,0 +1,8 @@
+/** @type {import('postcss').PostcssConfig} */
+module.exports = {
+  plugins: {
+    'postcss-import': {},
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

src/css/custom.css

@@ -17,3 +17,13 @@
 :root {
   /* add override here */
 }
+
+.breadcrumbs__link {
+  @apply !text-light-neutral-1 dark:!text-dark-neutral-1 !bg-transparent !p-0 !body-3;
+}
+.breadcrumbs__item:first-child, .breadcrumbs__item:first-child:after {
+  @apply !hidden;
+}
+.breadcrumbs__item:not(:last-child):after {
+  @apply !text-light-neutral-1 dark:!text-dark-neutral-1;
+}

src/css/font.css

@@ -2,77 +2,70 @@
 
 @font-face {
   font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Regular.woff2');
+  src: url('/static/fonts/baselGrotesk/Basel-Grotesk-Regular.woff2');
   font-weight: '400';
   font-style: 'normal';
 }
 
 @font-face {
   font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Regular-Italic.woff2');
+  src: url('/static/fonts/baselGrotesk/Basel-Grotesk-Regular-Italic.woff2');
   font-weight: '400';
   font-style: 'italic';
 }
 
 @font-face {
   font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Book.woff2');
+  src: url('/static/fonts/baselGrotesk/Basel-Grotesk-Book.woff2');
   font-weight: '500';
   font-style: 'normal';
 }
 
 @font-face {
   font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Book-Italic.woff2');
+  src: url('/static/fonts/baselGrotesk/Basel-Grotesk-Book-Italic.woff2');
   font-weight: '500';
   font-style: 'italic';
 }
 
 @font-face {
   font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Medium.woff2');
+  src: url('/static/fonts/baselGrotesk/Basel-Grotesk-Medium.woff2');
   font-weight: '600';
   font-style: 'normal';
 }
 
-@font-face {
-  font-family: 'Basel Grotesk';
-  src: url('/fonts/baselGrotesk/Basel-Grotesk-Medium-Italic.woff2');
-  font-weight: '600';
-  font-style: 'italic';
-}
-
 @font-face {
   font-family: 'Riegraf';
-  src: url('/fonts/riegraf/Riegraf-Light.otf');
+  src: url('/static/fonts/riegraf/Riegraf-Light.otf');
   font-weight: '300';
   font-style: 'normal';
 }
 
 @font-face {
   font-family: 'Riegraf';
-  src: url('/fonts/riegraf/Riegraf-Regular.otf');
+  src: url('/static/fonts/riegraf/Riegraf-Regular.otf');
   font-weight: '400';
   font-style: 'normal';
 }
 
 @font-face {
   font-family: 'Riegraf';
-  src: url('/fonts/riegraf/Riegraf-Regular-Italic.otf');
+  src: url('/static/fonts/riegraf/Riegraf-Regular-Italic.otf');
   font-weight: '400';
   font-style: 'italic';
 }
 
 @font-face {
   font-family: 'Riegraf';
-  src: url('/fonts/riegraf/Riegraf-Medium.otf');
+  src: url('/static/fonts/riegraf/Riegraf-Medium.otf');
   font-weight: '500';
   font-style: 'normal';
 }
 
 @font-face {
   font-family: 'Riegraf';
-  src: url('/fonts/riegraf/Riegraf-Bold.otf');
+  src: url('/static/fonts/riegraf/Riegraf-Bold.otf');
   font-weight: '600';
   font-style: 'normal';
 }

src/theme/DocBreadcrumbs.tsx

@@ -7,7 +7,7 @@ import SentimentTracking from '../components/SentimentTracking'
 export default function DocBreadcrumbs(props) {
   return (
     <div>
-      <OriginalDocBreadcrumbs {...props} />
+      <OriginalDocBreadcrumbs />
       <div>
         <SentimentTracking analyticsSection={DocsSentimentSection.TOP_SECTION} />
       </div>

src/theme/DocItem/Content/index.js

@@ -0,0 +1,38 @@
+import React from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+/**
+ 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() {
+  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}) {
+  const syntheticTitle = useSyntheticTitle();
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
+      {syntheticTitle && (
+        <header>
+          <Heading as="h1">{syntheticTitle}</Heading>
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  );
+}

src/theme/DocItem/Footer/index.js

@@ -0,0 +1,68 @@
+import React from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import LastUpdated from '@theme/LastUpdated';
+import EditThisPage from '@theme/EditThisPage';
+import TagsListInline from '@theme/TagsListInline';
+import styles from './styles.module.css';
+function TagsRow(props) {
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        'row margin-bottom--sm',
+      )}>
+      <div className="col">
+        <TagsListInline {...props} />
+      </div>
+    </div>
+  );
+}
+function EditMetaRow({
+  editUrl,
+  lastUpdatedAt,
+  lastUpdatedBy,
+  formattedLastUpdatedAt,
+}) {
+  return (
+    <div className={clsx(ThemeClassNames.docs.docFooterEditMetaRow, 'row')}>
+      <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
+
+      <div className={clsx('col', styles.lastUpdated)}>
+        {(lastUpdatedAt || lastUpdatedBy) && (
+          <LastUpdated
+            lastUpdatedAt={lastUpdatedAt}
+            formattedLastUpdatedAt={formattedLastUpdatedAt}
+            lastUpdatedBy={lastUpdatedBy}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+export default function DocItemFooter() {
+  const {metadata} = useDoc();
+  const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, 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 && <TagsRow tags={tags} />}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+          formattedLastUpdatedAt={formattedLastUpdatedAt}
+        />
+      )}
+    </footer>
+  );
+}

src/theme/DocItem/Footer/styles.module.css

@@ -0,0 +1,11 @@
+.lastUpdated {
+  margin-top: 0.2rem;
+  font-style: italic;
+  font-size: smaller;
+}
+
+@media (min-width: 997px) {
+  .lastUpdated {
+    text-align: right;
+  }
+}

src/theme/DocItem/Layout/index.js

@@ -0,0 +1,53 @@
+import React from 'react';
+import clsx from 'clsx';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+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 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}) {
+  const docTOC = useDocTOC();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <DocVersionBadge />
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && <div className="col col--3">On this page {docTOC.desktop}</div>}
+    </div>
+  );
+}

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

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

src/theme/DocItem/Metadata/index.js

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

src/theme/DocItem/Paginator/index.js

@@ -0,0 +1,11 @@
+import React from 'react';
+import {useDoc} from '@docusaurus/theme-common/internal';
+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() {
+  const {metadata} = useDoc();
+  return <DocPaginator previous={metadata.previous} next={metadata.next} />;
+}

src/theme/DocItem/TOC/Desktop/index.js

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

src/theme/DocItem/TOC/Mobile/index.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+import TOCCollapsible from '@theme/TOCCollapsible';
+import styles from './styles.module.css';
+export default function DocItemTOCMobile() {
+  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)}
+    />
+  );
+}

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

@@ -0,0 +1,12 @@
+@media (min-width: 997px) {
+  /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+  .tocMobile {
+    display: none;
+  }
+}
+
+@media print {
+  .tocMobile {
+    display: none;
+  }
+}