docs: improve layout, add tabs support to mdx files

packages/docs/gatsby-config.js → packages/docs/gatsby-config.mjs

@@ -1,4 +1,12 @@
-module.exports = {
+import remarkGfm from 'remark-gfm'
+import remarkCodeTabs from 'remark-code-tabs'
+
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const config = {
   siteMetadata: {
     title: `CoreUI for React.js`,
     titleTemplate: `%s · React UI Components · CoreUI `,
@@ -52,10 +60,7 @@ module.exports = {
       resolve: `gatsby-plugin-mdx`,
       options: {
         mdxOptions: {
-          remarkPlugins: [
-            // Add GitHub Flavored Markdown (GFM) support
-            require(`remark-gfm`),
-          ],
+          remarkPlugins: [remarkGfm, remarkCodeTabs],
         },
         gatsbyRemarkPlugins: [
           {
@@ -99,3 +104,5 @@ module.exports = {
     },
   ],
 }
+
+export default config

packages/docs/gatsby-node.js → packages/docs/gatsby-node.mjs

@@ -1,7 +1,12 @@
-const path = require('node:path')
-const { createFilePath } = require('gatsby-source-filesystem')
+import { resolve } from 'node:path'
+import { createFilePath } from 'gatsby-source-filesystem'
 
-exports.onCreateNode = async ({ node, loadNodeContent, actions: { createNodeField }, getNode }) => {
+export const onCreateNode = async ({
+  node,
+  loadNodeContent,
+  actions: { createNodeField },
+  getNode,
+}) => {
   if (node.internal.type === 'Mdx') {
     const slug = createFilePath({ node, getNode })
 
@@ -22,7 +27,11 @@ exports.onCreateNode = async ({ node, loadNodeContent, actions: { createNodeFiel
   }
 }
 
-exports.createPages = async ({ graphql, actions: { createPage, createRedirect }, reporter }) => {
+export const createPages = async ({
+  graphql,
+  actions: { createPage, createRedirect },
+  reporter,
+}) => {
   const result = await graphql(`
     query {
       allMdx {
@@ -50,7 +59,7 @@ exports.createPages = async ({ graphql, actions: { createPage, createRedirect },
     posts.forEach((node) => {
       createPage({
         path: node.fields.slug,
-        component: `${path.resolve(`./src/templates/MdxLayout.tsx`)}?__contentFilePath=${
+        component: `${resolve(`./src/templates/MdxLayout.tsx`)}?__contentFilePath=${
           node.internal.contentFilePath
         }`,
         context: { id: node.id },

packages/docs/src/components/ScssDocs.tsx

@@ -43,7 +43,7 @@ const ScssDocs = ({ file, capture }: ScssDocsProps) => {
 
   return (
     code && (
-      <div className="highlight">
+      <div className="highlight mb-3">
         <Highlight
           code={code
             .replaceAll('--#{$prefix}', '--cui-')

packages/docs/src/components/Toc.tsx

@@ -1,5 +1,5 @@
-import React, { FC } from 'react'
-import { CNav } from '@coreui/react/src/index'
+import React, { FC, useState } from 'react'
+import { CCollapse, CNav } from '@coreui/react/src/index'
 
 type TocItem = {
   url: string
@@ -11,34 +11,58 @@ interface TocProps {
   items: TocItem[]
 }
 
-const Toc: FC<TocProps> = ({ items }) => {
-  const toc = (items: TocItem[]) => {
-    return (
-      items &&
-      items.map((item, index) => {
-        if (Array.isArray(item.items)) {
-          return (
-            <li key={index}>
-              <a href={item.url}>{item.title}</a>
-              <ul>{toc(item.items)}</ul>
-            </li>
-          )
-        }
+const toc = (items: TocItem[]) => {
+  return (
+    items &&
+    items.map((item, index) => {
+      if (Array.isArray(item.items)) {
         return (
           <li key={index}>
             <a href={item.url}>{item.title}</a>
+            <ul>{toc(item.items)}</ul>
           </li>
         )
-      })
-    )
-  }
+      }
+      return (
+        <li key={index}>
+          <a href={item.url}>{item.title}</a>
+        </li>
+      )
+    })
+  )
+}
 
+const Toc: FC<TocProps> = ({ items }) => {
+  const [visible, setVisible] = useState(false)
   return (
     <div className="docs-toc mt-4 mb-5 my-md-0 ps-xl-5 mb-lg-5 text-body-secondary">
-      <strong className="d-block h6 mb-2 pb-2 border-bottom">On this page</strong>
-      <CNav as="nav" className="flex-column">
-        <ul>{toc(items)}</ul>
-      </CNav>
+      <button
+        className="btn btn-link p-md-0 mb-2 mb-md-0 text-decoration-none docs-toc-toggle d-md-none"
+        type="button"
+        aria-expanded={visible ? true : false}
+        aria-controls="tocContents"
+        onClick={() => setVisible(!visible)}
+      >
+        On this page
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          className="icon d-md-none ms-2"
+          aria-hidden="true"
+          viewBox="0 0 512 512"
+        >
+          <polygon
+            fill="var(--ci-primary-color, currentColor)"
+            points="256 382.627 60.687 187.313 83.313 164.687 256 337.372 428.687 164.687 451.313 187.313 256 382.627"
+            className="ci-primary"
+          />
+        </svg>
+      </button>
+      <strong className="d-none d-md-block h6 mb-2 pb-2 border-bottom">On this page</strong>
+      <CCollapse className="docs-toc-collapse" id="tocContents" visible={visible}>
+        <CNav as="nav">
+          <ul>{toc(items)}</ul>
+        </CNav>
+      </CCollapse>
     </div>
   )
 }

packages/docs/src/styles/_component-examples.scss

@@ -2,6 +2,14 @@
 // Docs examples
 //
 
+.tab-content .tab-pane {
+  @include border-top-radius(0);
+
+  .highlight {
+    @include border-top-radius(0);
+  }
+}
+
 .docs-example-snippet {
   border: solid var(--cui-border-color);
   border-width: 1px 0;
@@ -373,19 +381,20 @@
 .highlight {
   position: relative;
   padding: .75rem ($cd-gutter-x * .5);
-  margin-bottom: 1rem;
+  margin: 0 ($cd-gutter-x * -.5) 1rem ($cd-gutter-x * -.5) ;
   border: 1px solid var(--cui-border-color);
   background-color: var(--cd-pre-bg);
 
   @include media-breakpoint-up(md) {
     padding: .75rem 1.25rem;
+    margin-right: 0;
+    margin-left: 0;
     @include border-radius(var(--cui-border-radius));
   }
 
   pre {
     padding: .25rem 0 .875rem;
     margin-top: .8125rem;
-    margin-right: 1.875rem;
     margin-bottom: 0;
     overflow: overlay;
     white-space: pre;
@@ -404,7 +413,7 @@
   margin: 0 ($cd-gutter-x * -.5) $spacer;
 
   .highlight {
-    margin-bottom: 0;
+    margin: 0;
   }
 
   .docs-example ~ .highlight {

packages/docs/src/styles/_layout.scss

@@ -3,4 +3,52 @@
   @include ltr-rtl("padding-left", var(--cui-sidebar-occupy-start, 0));
   will-change: auto;
   @include transition(padding .15s);
+
+  > .container-lg {
+    --cui-gutter-x: 3rem;
+  }
+}
+
+.docs-sidebar {
+  grid-area: sidebar;
+}
+
+.docs-main {
+  grid-area: main;
+
+  @include media-breakpoint-down(lg) {
+    max-width: 760px;
+    margin-inline: auto;
+  }
+
+  @include media-breakpoint-up(md) {
+    display: grid;
+    grid-template-areas:
+      "intro"
+      "toc"
+      "content";
+    grid-template-rows: auto auto 1fr;
+    gap: $grid-gutter-width;
+  }
+
+  @include media-breakpoint-up(lg) {
+    grid-template-areas:
+      "intro   toc"
+      "content toc";
+    grid-template-rows: auto 1fr;
+    grid-template-columns: 4fr 1fr;
+  }
+}
+
+.docs-intro {
+  grid-area: intro;
+}
+
+.docs-toc {
+  grid-area: toc;
+}
+
+.docs-content {
+  grid-area: content;
+  min-width: 1px; // Fix width when bd-content contains a `<pre>` https://github.com/twbs/bootstrap/issues/25410
 }

packages/docs/src/styles/_toc.scss

@@ -39,4 +39,49 @@
       }
     }
   }
-}
+}
+
+.docs-toc-toggle {
+  display: flex;
+  align-items: center;
+
+  @include media-breakpoint-down(sm) {
+    justify-content: space-between;
+    width: 100%;
+  }
+
+  @include media-breakpoint-down(md) {
+    color: var(--cui-body-color);
+    border: 1px solid var(--cui-border-color);
+    @include border-radius(var(--cui-border-radius));
+
+    &:hover,
+    &:focus,
+    &:active,
+    &[aria-expanded="true"] {
+      color: var(--cui-primary);
+      background-color: var(--cui-body-bg);
+      border-color: var(--cui-primary);
+    }
+
+    &:focus,
+    &[aria-expanded="true"] {
+      box-shadow: 0 0 0 3px rgba(var(--cui-primary-rgb), .25);
+    }
+  }
+}
+
+.docs-toc-collapse {
+  @include media-breakpoint-down(md) {
+    nav {
+      padding: 1.25rem 1.25rem 1.25rem 1rem;
+      background-color: var(--cui-tertiary-bg);
+      border: 1px solid var(--cui-border-color);
+      @include border-radius(var(--cui-border-radius));
+    }
+  }
+
+  @include media-breakpoint-up(md) {
+    display: block !important; // stylelint-disable-line declaration-no-important
+  }
+}

packages/docs/src/templates/DefaultLayout.tsx

@@ -29,17 +29,15 @@ const DefaultLayout: FC<DefaultLayoutProps> = ({ children, data, pageContext, pa
     >
       <Seo title={title} description={description} name={name} />
       <Sidebar />
-      <div className="wrapper d-flex flex-column min-vh-100">
+      <div className="wrapper flex-grow-1">
         <Header />
-        <div className="body flex-grow-1 px-3">
-          {path === '/404/' ? (
-            <CContainer lg>{children}</CContainer>
-          ) : (
-            <DocsLayout data={data} pageContext={pageContext}>
-              {children}
-            </DocsLayout>
-          )}
-        </div>
+        {path === '/404/' ? (
+          <CContainer lg>{children}</CContainer>
+        ) : (
+          <DocsLayout data={data} pageContext={pageContext}>
+            {children}
+          </DocsLayout>
+        )}
         <Footer />
       </div>
       <Script