[docs] More docs infra changes

* Separate text content and it's wrapper's styles * More use of env variables for constants * Use docs infra config from @mui/monorepo * Correctly link md or mdx files to Github * Hide version selector if it has only one version * Simplify and enable bottom pagination style * Setup code highlighting of mdx code content with built-in shiki theme
mui · Nov 6, 2024 · b7ef6f7 · b7ef6f7
1 parent 042b771
commit b7ef6f7
Show file tree

Hide file tree

Showing 17 changed files with 637 additions and 472 deletions.
diff --git a/docs/globals.d.ts b/docs/globals.d.ts
@@ -0,0 +1,10 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      NODE_ENV: string;
+      REPO_ROOT: string;
+      DATA_DIR: string;
+      DEFAULT_BRANCH: string;
+    }
+  }
+}
diff --git a/docs/next.config.ts b/docs/next.config.ts
@@ -1,20 +1,38 @@
+import * as url from 'url';
+import * as path from 'path';
 import type { NextConfig } from 'next';
+// @ts-ignore
+// eslint-disable-next-line no-restricted-imports
+import withDocsInfra from '@mui/monorepo/docs/nextConfigDocsInfra.js';
 import { withPigment, extendTheme } from '@pigment-css/nextjs-plugin';
-import path from 'path';
+
 import { theme as baseTheme } from './src/theme';
+import rootPackage from '../package.json';
 
-const DATA_DIR = path.join(process.cwd(), 'data');
+const currentDirectory = url.fileURLToPath(new URL('.', import.meta.url));
+const DATA_DIR = path.join(currentDirectory, 'data');
 
 const nextConfig: NextConfig = {
   trailingSlash: false,
   env: {
     DATA_DIR,
+    CURRENT_VERSION: rootPackage.version,
   },
   distDir: 'export',
   output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
   eslint: {
     ignoreDuringBuilds: true,
   },
+  devIndicators: {
+    buildActivity: true,
+    buildActivityPosition: 'bottom-right',
+    appIsrStatus: false,
+  },
+  experimental: {
+    esmExternals: true,
+    workerThreads: false,
+    turbo: undefined,
+  },
 };
 
 const theme = extendTheme({
@@ -23,11 +41,14 @@ const theme = extendTheme({
   },
 });
 
-export default withPigment(nextConfig, {
+export default withPigment(withDocsInfra(nextConfig), {
   theme,
   displayName: true,
-  sourceMap: true,
+  sourceMap: process.env.NODE_ENV !== 'production',
   babelOptions: {
-    plugins: ['@babel/plugin-proposal-explicit-resource-management'],
+    plugins: [
+      '@babel/plugin-proposal-explicit-resource-management',
+      '@babel/plugin-transform-unicode-property-regex',
+    ],
   },
 });
diff --git a/docs/package.json b/docs/package.json
@@ -15,18 +15,22 @@
     "@pigment-css/react": "workspace:*",
     "@stefanprobst/rehype-extract-toc": "^2.2.0",
     "clsx": "^2.1.1",
+    "next": "15.0.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "next": "15.0.2",
+    "rehype-pretty-code": "0.14.0",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
     "remark-mdx-frontmatter": "^5.0.0",
+    "shiki": "^1.22.2",
     "to-vfile": "^8.0.0",
     "vfile-matter": "^5.0.0"
   },
   "devDependencies": {
     "@babel/plugin-proposal-explicit-resource-management": "^7.25.9",
+    "@babel/plugin-transform-unicode-property-regex": "^7.25.9",
+    "@mui/monorepo": "github:mui/material-ui#ae455647016fe5dee968b017aa191e176bc113dd",
     "@pigment-css/nextjs-plugin": "workspace:*",
     "@types/node": "^20",
     "@types/react": "^18",

diff --git a/docs/src/app/(content)/getting-started/[slug]/not-found.tsx b/docs/src/app/(content)/getting-started/[slug]/not-found.tsx
@@ -1,11 +1,17 @@
 import * as React from 'react';
-import { MainContent } from '@/components/MainContent';
+import { MainContent, MainContentContainer } from '@/components/MainContent';
+import { Description } from '@/components/mdx/Description';
 
 export default function NotFoundPage() {
   return (
-    <MainContent as="main">
-      <h1>Not Found</h1>
-      <p>The page that you were looking for could not be found.</p>
-    </MainContent>
+    <MainContentContainer as="main">
+      <MainContent sx={{ textAlign: 'center' }}>
+        <h1>Page not found</h1>
+        <Description>
+          Apologies, but the page you were looking for wasn&apos;t found. Try reaching for the
+          search button on the nav bar above to look for another one.
+        </Description>
+      </MainContent>
+    </MainContentContainer>
   );
 }
diff --git a/docs/src/app/(content)/getting-started/[slug]/page.tsx b/docs/src/app/(content)/getting-started/[slug]/page.tsx
@@ -1,12 +1,13 @@
 import * as React from 'react';
 import { notFound } from 'next/navigation';
-import { getSlugs } from '@data/pages';
 import { Metadata } from 'next';
-import { getMarkdownPage, getMarkdownPageMetadata } from '@data/getMarkdownPage';
+import routes, { getSlugs } from '@data/pages';
+import { EditPageOnGithub } from '@/components/EditPageOnGithub';
+import { SiblingPageLinks } from '@/components/SiblingPageLinks';
 import { TableOfContents } from '@/components/TableOfContents';
 import { Description } from '@/components/mdx/Description';
 import { components } from '@/components/mdx/MDXComponents';
-import { MainContent } from '@/components/MainContent';
+import { MainContentContainer, MainContent } from '@/components/MainContent';
 
 interface Props {
   params: Promise<{ slug: string }>;
@@ -16,8 +17,9 @@ const SEGMENT = 'getting-started';
 
 export default async function GettingStartedPage(props: Props) {
   const { slug } = await props.params;
+  const { getMarkdownPage } = await import('@/utils/getMarkdownPage');
   try {
-    const { MDXContent, metadata, tableOfContents } = await getMarkdownPage(SEGMENT, slug);
+    const { isMd, MDXContent, metadata, tableOfContents } = await getMarkdownPage(SEGMENT, slug);
     const allComponents = {
       ...components,
       Description: () => <Description className="description" text={metadata.description} />,
@@ -26,22 +28,31 @@ export default async function GettingStartedPage(props: Props) {
 
     return (
       <React.Fragment>
-        <MainContent as="main">
-          <MDXContent components={allComponents} />
-          {/* <div>
-            <div
+        <MainContentContainer as="main">
+          <MainContent>
+            <MDXContent components={allComponents} />
+          </MainContent>
+          <footer
+            sx={{
+              padding: 'var(--space-9) 0',
+            }}
+          >
+            <div>
+              <EditPageOnGithub category={SEGMENT} slug={slug} isMd={isMd} />
+            </div>
+            <hr
               sx={{
-                padding: 'var(--space-9) 0',
+                margin: 'var(--space-4) 0',
+                borderWidth: '0 0 thin',
+                borderStyle: 'solid',
+                borderColor: 'var(--gray-outline-1)',
               }}
-            >
-              <EditPageOnGithub category={SEGMENT} slug={slug} />
-            </div>
+            />
             <div>
               <SiblingPageLinks currentSlug={`/${SEGMENT}/${slug}`} pages={routes} />
             </div>
-          </div> */}
-        </MainContent>
-
+          </footer>
+        </MainContentContainer>
         <TableOfContents toc={tableOfContents} />
       </React.Fragment>
     );
@@ -58,6 +69,7 @@ export function generateStaticParams() {
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { getMarkdownPageMetadata } = await import('@/utils/getMarkdownPage');
   const { slug } = await params;
   const { title = 'Getting started', description } = await getMarkdownPageMetadata(SEGMENT, slug);
 

diff --git a/docs/src/app/favicon.ico b/docs/src/app/favicon.ico
diff --git a/docs/src/app/globals.css b/docs/src/app/globals.css
@@ -27,9 +27,27 @@ body {
     text-decoration: none;
   }
 }
-/* 
-@media (prefers-color-scheme: dark) {
-  html {
-    color-scheme: dark;
-  }
-} */
+
+.shiki,
+.shiki span,
+[data-theme],
+[data-theme] span {
+  color: var(--shiki-light) !important;
+  background-color: var(--shiki-light-bg) !important;
+  /* Optional, if you also want font styles */
+  font-style: var(--shiki-light-font-style) !important;
+  font-weight: var(--shiki-light-font-weight) !important;
+  text-decoration: var(--shiki-light-text-decoration) !important;
+}
+
+html.dark .shiki,
+html.dark [data-theme],
+html.dark .shiki span,
+html.dark [data-theme] span {
+  color: var(--shiki-dark) !important;
+  background-color: var(--shiki-dark-bg) !important;
+  /* Optional, if you also want font styles */
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}
diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx
@@ -18,6 +18,7 @@ const geistMono = localFont({
 export const metadata: Metadata = {
   title: 'Create Next App',
   description: 'Generated by create next app',
+  generator: `Pigment Docs (Next.js)${process.env.COMMIT_REF ? ` ${process.env.COMMIT_REF}` : ''}`,
 };
 
 export default function RootLayout({

diff --git a/docs/src/components/AppBar.tsx b/docs/src/components/AppBar.tsx
@@ -45,7 +45,9 @@ export function AppBar() {
         <IconLinkButton useNextLink href="/" label="Pigment CSS" size={3}>
           <PigmentIcon />
         </IconLinkButton>
-        <DocsVersionSelector currentVersion={currentVersion} versions={supportedVersions} />
+        {supportedVersions.length > 1 && (
+          <DocsVersionSelector currentVersion={currentVersion} versions={supportedVersions} />
+        )}
       </div>
       <div
         sx={{
@@ -54,7 +56,7 @@ export function AppBar() {
         }}
       >
         <IconLinkButton
-          href="https://github.com/mui/pigment-css"
+          href={process.env.REPO_ROOT}
           target="_blank"
           label="GitHub"
           rel="noreferrer noopener"

diff --git a/docs/src/components/EditPageOnGithub.tsx b/docs/src/components/EditPageOnGithub.tsx
@@ -1,22 +1,20 @@
-import { styled } from '@pigment-css/react';
+import { css } from '@pigment-css/react';
 import * as React from 'react';
+import Link from 'next/link';
+import { GitHubIcon } from './icons/Github';
 
 export interface EditPageOnGithubProps {
   category: string;
   slug: string;
+  isMd: boolean;
 }
 
-const REPO_ROOT = 'https://github.com/mui/pigment-css';
-// #default-branch-switch
-const DEFAULT_BRANCH = 'master';
-
-const Link = styled.a(({ theme }) => ({
+const linkClass = css(({ theme }) => ({
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: theme.vars.space[1],
   cursor: 'pointer',
-  textDecoration: 'underline',
-  textDecorationLine: 'underline',
-  textDecorationStyle: 'solid',
-  textDecorationThickness: '1px',
-  textUnderlineOffset: 'calc(0.1em + 3px)',
+  textDecoration: 'none !important',
   color: 'inherit',
   position: 'relative',
   zIndex: 0,
@@ -27,12 +25,13 @@ const Link = styled.a(({ theme }) => ({
 }));
 
 export function EditPageOnGithub(props: EditPageOnGithubProps) {
-  const { category, slug } = props;
+  const { category, slug, isMd } = props;
 
-  const url = `${REPO_ROOT}/edit/${DEFAULT_BRANCH}/docs/data/${category}/${slug}/${slug}.mdx`;
+  const url = `${process.env.REPO_ROOT}/edit/${process.env.DEFAULT_BRANCH}/docs/data/${category}/${slug}/${slug}.${isMd ? 'md' : 'mdx'}`;
   return (
-    <Link href={url} target="_blank" rel="noopener nofollow">
-      Edit this page on GitHub
+    <Link href={url} className={linkClass} target="_blank" rel="noopener nofollow">
+      <GitHubIcon />
+      <span>Edit this page</span>
     </Link>
   );
 }
diff --git a/docs/src/components/MainContent.tsx b/docs/src/components/MainContent.tsx
@@ -1,18 +1,21 @@
 import { styled } from '@pigment-css/react';
 
-export const MainContent = styled.div({
+export const MainContentContainer = styled.div(({ theme }) => ({
   boxSizing: 'content-box',
-  maxWidth: '714px',
-  paddingTop: 'var(--space-9)',
-  paddingLeft: 'var(--space-6)',
-  paddingRight: 'var(--space-6)',
+  maxWidth: 714,
+  paddingTop: theme.vars.space[9],
+  paddingLeft: theme.vars.space[6],
+  paddingRight: theme.vars.space[6],
   marginLeft: 'auto',
   marginRight: 'auto',
-  marginBottom: 'var(--space-9)',
+  marginBottom: theme.vars.space[9],
   '@media (max-width: 1242px)': {
     marginRight: 'calc((100vw - 240px - 762px) / 2)',
   },
   '@media (max-width: 1002px)': { marginLeft: 'auto', marginRight: 'auto' },
+}));
+
+export const MainContent = styled.div({
   'p:not(.description)': {
     margin: '0',
     marginBottom: 'var(--space-4)',
@@ -71,6 +74,17 @@ export const MainContent = styled.div({
     letterSpacing: '-0.012em',
   },
   code: { fontFamily: 'var(--ff-code)' },
+  'pre[data-language]': {
+    position: 'relative',
+    '&::after': {
+      position: 'absolute',
+      top: 5,
+      right: 10,
+      opacity: 0.5,
+      fontSize: '0.8rem',
+      content: 'attr(data-language)',
+    },
+  },
   ':not(pre) > code': {
     marginLeft: '1px',
     marginRight: '1px',
@@ -105,7 +119,7 @@ export const MainContent = styled.div({
     whiteSpace: 'pre',
     color: 'var(--gray-text-1)',
     border: '1px solid var(--gray-outline-2)',
-    borderRadius: '12px',
+    borderRadius: 8,
   },
   kbd: {
     padding: '6px',