Skip to content

Commit abc48b8

Browse files
author
Brijesh Bittu
committed
[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
1 parent 85ea2f6 commit abc48b8

19 files changed

+640
-475
lines changed

‎docs/.env

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
REPO_ROOT=https://github.com/mui/pigment-css
2+
DEFAULT_BRANCH=master
3+

‎docs/.gitignore

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,6 @@ npm-debug.log*
2929
yarn-debug.log*
3030
yarn-error.log*
3131

32-
# env files (can opt-in for commiting if needed)
33-
.env*
34-
3532
# vercel
3633
.vercel
3734

‎docs/globals.d.ts

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
declare global {
2+
namespace NodeJS {
3+
interface ProcessEnv {
4+
NODE_ENV: string;
5+
REPO_ROOT: string;
6+
DATA_DIR: string;
7+
DEFAULT_BRANCH: string;
8+
}
9+
}
10+
}

‎docs/next.config.ts

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,38 @@
1+
import * as url from 'url';
2+
import * as path from 'path';
13
import type { NextConfig } from 'next';
4+
// @ts-ignore
5+
// eslint-disable-next-line no-restricted-imports
6+
import withDocsInfra from '@mui/monorepo/docs/nextConfigDocsInfra.js';
27
import { withPigment, extendTheme } from '@pigment-css/nextjs-plugin';
3-
import path from 'path';
8+
49
import { theme as baseTheme } from './src/theme';
10+
import rootPackage from '../package.json';
511

6-
const DATA_DIR = path.join(process.cwd(), 'data');
12+
const currentDirectory = url.fileURLToPath(new URL('.', import.meta.url));
13+
const DATA_DIR = path.join(currentDirectory, 'data');
714

815
const nextConfig: NextConfig = {
916
trailingSlash: false,
1017
env: {
1118
DATA_DIR,
19+
CURRENT_VERSION: rootPackage.version,
1220
},
1321
distDir: 'export',
1422
output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
1523
eslint: {
1624
ignoreDuringBuilds: true,
1725
},
26+
devIndicators: {
27+
buildActivity: true,
28+
buildActivityPosition: 'bottom-right',
29+
appIsrStatus: false,
30+
},
31+
experimental: {
32+
esmExternals: true,
33+
workerThreads: false,
34+
turbo: undefined,
35+
},
1836
};
1937

2038
const theme = extendTheme({
@@ -23,11 +41,14 @@ const theme = extendTheme({
2341
},
2442
});
2543

26-
export default withPigment(nextConfig, {
44+
export default withPigment(withDocsInfra(nextConfig), {
2745
theme,
2846
displayName: true,
29-
sourceMap: true,
47+
sourceMap: process.env.NODE_ENV !== 'production',
3048
babelOptions: {
31-
plugins: ['@babel/plugin-proposal-explicit-resource-management'],
49+
plugins: [
50+
'@babel/plugin-proposal-explicit-resource-management',
51+
'@babel/plugin-transform-unicode-property-regex',
52+
],
3253
},
3354
});

‎docs/package.json

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,22 @@
1515
"@pigment-css/react": "workspace:*",
1616
"@stefanprobst/rehype-extract-toc": "^2.2.0",
1717
"clsx": "^2.1.1",
18+
"next": "15.0.2",
1819
"react": "18.3.1",
1920
"react-dom": "18.3.1",
20-
"next": "15.0.2",
21+
"rehype-pretty-code": "0.14.0",
2122
"rehype-slug": "^6.0.0",
2223
"remark-frontmatter": "^5.0.0",
2324
"remark-gfm": "^4.0.0",
2425
"remark-mdx-frontmatter": "^5.0.0",
26+
"shiki": "^1.22.2",
2527
"to-vfile": "^8.0.0",
2628
"vfile-matter": "^5.0.0"
2729
},
2830
"devDependencies": {
2931
"@babel/plugin-proposal-explicit-resource-management": "^7.25.9",
32+
"@babel/plugin-transform-unicode-property-regex": "^7.25.9",
33+
"@mui/monorepo": "github:mui/material-ui#ae455647016fe5dee968b017aa191e176bc113dd",
3034
"@pigment-css/nextjs-plugin": "workspace:*",
3135
"@types/node": "^20",
3236
"@types/react": "^18",

‎docs/src/app/(content)/getting-started/[slug]/not-found.tsx

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
import * as React from 'react';
2-
import { MainContent } from '@/components/MainContent';
2+
import { MainContent, MainContentContainer } from '@/components/MainContent';
3+
import { Description } from '@/components/mdx/Description';
34

45
export default function NotFoundPage() {
56
return (
6-
<MainContent as="main">
7-
<h1>Not Found</h1>
8-
<p>The page that you were looking for could not be found.</p>
9-
</MainContent>
7+
<MainContentContainer as="main">
8+
<MainContent sx={{ textAlign: 'center' }}>
9+
<h1>Page not found</h1>
10+
<Description>
11+
Apologies, but the page you were looking for wasn&apos;t found. Try reaching for the
12+
search button on the nav bar above to look for another one.
13+
</Description>
14+
</MainContent>
15+
</MainContentContainer>
1016
);
1117
}

‎docs/src/app/(content)/getting-started/[slug]/page.tsx

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
import * as React from 'react';
22
import { notFound } from 'next/navigation';
3-
import { getSlugs } from '@data/pages';
43
import { Metadata } from 'next';
5-
import { getMarkdownPage, getMarkdownPageMetadata } from '@data/getMarkdownPage';
4+
import routes, { getSlugs } from '@data/pages';
5+
import { EditPageOnGithub } from '@/components/EditPageOnGithub';
6+
import { SiblingPageLinks } from '@/components/SiblingPageLinks';
67
import { TableOfContents } from '@/components/TableOfContents';
78
import { Description } from '@/components/mdx/Description';
89
import { components } from '@/components/mdx/MDXComponents';
9-
import { MainContent } from '@/components/MainContent';
10+
import { MainContentContainer, MainContent } from '@/components/MainContent';
1011

1112
interface Props {
1213
params: Promise<{ slug: string }>;
@@ -16,8 +17,9 @@ const SEGMENT = 'getting-started';
1617

1718
export default async function GettingStartedPage(props: Props) {
1819
const { slug } = await props.params;
20+
const { getMarkdownPage } = await import('@/utils/getMarkdownPage');
1921
try {
20-
const { MDXContent, metadata, tableOfContents } = await getMarkdownPage(SEGMENT, slug);
22+
const { isMd, MDXContent, metadata, tableOfContents } = await getMarkdownPage(SEGMENT, slug);
2123
const allComponents = {
2224
...components,
2325
Description: () => <Description className="description" text={metadata.description} />,
@@ -26,22 +28,31 @@ export default async function GettingStartedPage(props: Props) {
2628

2729
return (
2830
<React.Fragment>
29-
<MainContent as="main">
30-
<MDXContent components={allComponents} />
31-
{/* <div>
32-
<div
31+
<MainContentContainer as="main">
32+
<MainContent>
33+
<MDXContent components={allComponents} />
34+
</MainContent>
35+
<footer
36+
sx={{
37+
padding: 'var(--space-9) 0',
38+
}}
39+
>
40+
<div>
41+
<EditPageOnGithub category={SEGMENT} slug={slug} isMd={isMd} />
42+
</div>
43+
<hr
3344
sx={{
34-
padding: 'var(--space-9) 0',
45+
margin: 'var(--space-4) 0',
46+
borderWidth: '0 0 thin',
47+
borderStyle: 'solid',
48+
borderColor: 'var(--gray-outline-1)',
3549
}}
36-
>
37-
<EditPageOnGithub category={SEGMENT} slug={slug} />
38-
</div>
50+
/>
3951
<div>
4052
<SiblingPageLinks currentSlug={`/${SEGMENT}/${slug}`} pages={routes} />
4153
</div>
42-
</div> */}
43-
</MainContent>
44-
54+
</footer>
55+
</MainContentContainer>
4556
<TableOfContents toc={tableOfContents} />
4657
</React.Fragment>
4758
);
@@ -58,6 +69,7 @@ export function generateStaticParams() {
5869
}
5970

6071
export async function generateMetadata({ params }: Props): Promise<Metadata> {
72+
const { getMarkdownPageMetadata } = await import('@/utils/getMarkdownPage');
6173
const { slug } = await params;
6274
const { title = 'Getting started', description } = await getMarkdownPageMetadata(SEGMENT, slug);
6375

‎docs/src/app/favicon.ico

-23.6 KB
Binary file not shown.

‎docs/src/app/globals.css

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,27 @@ body {
2727
text-decoration: none;
2828
}
2929
}
30-
/*
31-
@media (prefers-color-scheme: dark) {
32-
html {
33-
color-scheme: dark;
34-
}
35-
} */
30+
31+
.shiki,
32+
.shiki span,
33+
[data-theme],
34+
[data-theme] span {
35+
color: var(--shiki-light) !important;
36+
background-color: var(--shiki-light-bg) !important;
37+
/* Optional, if you also want font styles */
38+
font-style: var(--shiki-light-font-style) !important;
39+
font-weight: var(--shiki-light-font-weight) !important;
40+
text-decoration: var(--shiki-light-text-decoration) !important;
41+
}
42+
43+
html.dark .shiki,
44+
html.dark [data-theme],
45+
html.dark .shiki span,
46+
html.dark [data-theme] span {
47+
color: var(--shiki-dark) !important;
48+
background-color: var(--shiki-dark-bg) !important;
49+
/* Optional, if you also want font styles */
50+
font-style: var(--shiki-dark-font-style) !important;
51+
font-weight: var(--shiki-dark-font-weight) !important;
52+
text-decoration: var(--shiki-dark-text-decoration) !important;
53+
}

‎docs/src/app/layout.tsx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ const geistMono = localFont({
1818
export const metadata: Metadata = {
1919
title: 'Create Next App',
2020
description: 'Generated by create next app',
21+
generator: `Pigment Docs (Next.js)${process.env.COMMIT_REF ? ` ${process.env.COMMIT_REF}` : ''}`,
2122
};
2223

2324
export default function RootLayout({

‎docs/src/components/AppBar.tsx

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,9 @@ export function AppBar() {
4545
<IconLinkButton useNextLink href="/" label="Pigment CSS" size={3}>
4646
<PigmentIcon />
4747
</IconLinkButton>
48-
<DocsVersionSelector currentVersion={currentVersion} versions={supportedVersions} />
48+
{supportedVersions.length > 1 && (
49+
<DocsVersionSelector currentVersion={currentVersion} versions={supportedVersions} />
50+
)}
4951
</div>
5052
<div
5153
sx={{
@@ -54,7 +56,7 @@ export function AppBar() {
5456
}}
5557
>
5658
<IconLinkButton
57-
href="https://github.com/mui/pigment-css"
59+
href={process.env.REPO_ROOT}
5860
target="_blank"
5961
label="GitHub"
6062
rel="noreferrer noopener"

‎docs/src/components/EditPageOnGithub.tsx

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,20 @@
1-
import { styled } from '@pigment-css/react';
1+
import { css } from '@pigment-css/react';
22
import * as React from 'react';
3+
import Link from 'next/link';
4+
import { GitHubIcon } from './icons/Github';
35

46
export interface EditPageOnGithubProps {
57
category: string;
68
slug: string;
9+
isMd: boolean;
710
}
811

9-
const REPO_ROOT = 'https://github.com/mui/pigment-css';
10-
// #default-branch-switch
11-
const DEFAULT_BRANCH = 'master';
12-
13-
const Link = styled.a(({ theme }) => ({
12+
const linkClass = css(({ theme }) => ({
13+
display: 'inline-flex',
14+
alignItems: 'center',
15+
gap: theme.vars.space[1],
1416
cursor: 'pointer',
15-
textDecoration: 'underline',
16-
textDecorationLine: 'underline',
17-
textDecorationStyle: 'solid',
18-
textDecorationThickness: '1px',
19-
textUnderlineOffset: 'calc(0.1em + 3px)',
17+
textDecoration: 'none !important',
2018
color: 'inherit',
2119
position: 'relative',
2220
zIndex: 0,
@@ -27,12 +25,13 @@ const Link = styled.a(({ theme }) => ({
2725
}));
2826

2927
export function EditPageOnGithub(props: EditPageOnGithubProps) {
30-
const { category, slug } = props;
28+
const { category, slug, isMd } = props;
3129

32-
const url = `${REPO_ROOT}/edit/${DEFAULT_BRANCH}/docs/data/${category}/${slug}/${slug}.mdx`;
30+
const url = `${process.env.REPO_ROOT}/edit/${process.env.DEFAULT_BRANCH}/docs/data/${category}/${slug}/${slug}.${isMd ? 'md' : 'mdx'}`;
3331
return (
34-
<Link href={url} target="_blank" rel="noopener nofollow">
35-
Edit this page on GitHub
32+
<Link href={url} className={linkClass} target="_blank" rel="noopener nofollow">
33+
<GitHubIcon />
34+
<span>Edit this page</span>
3635
</Link>
3736
);
3837
}

‎docs/src/components/MainContent.tsx

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,21 @@
11
import { styled } from '@pigment-css/react';
22

3-
export const MainContent = styled.div({
3+
export const MainContentContainer = styled.div(({ theme }) => ({
44
boxSizing: 'content-box',
5-
maxWidth: '714px',
6-
paddingTop: 'var(--space-9)',
7-
paddingLeft: 'var(--space-6)',
8-
paddingRight: 'var(--space-6)',
5+
maxWidth: 714,
6+
paddingTop: theme.vars.space[9],
7+
paddingLeft: theme.vars.space[6],
8+
paddingRight: theme.vars.space[6],
99
marginLeft: 'auto',
1010
marginRight: 'auto',
11-
marginBottom: 'var(--space-9)',
11+
marginBottom: theme.vars.space[9],
1212
'@media (max-width: 1242px)': {
1313
marginRight: 'calc((100vw - 240px - 762px) / 2)',
1414
},
1515
'@media (max-width: 1002px)': { marginLeft: 'auto', marginRight: 'auto' },
16+
}));
17+
18+
export const MainContent = styled.div({
1619
'p:not(.description)': {
1720
margin: '0',
1821
marginBottom: 'var(--space-4)',
@@ -71,6 +74,17 @@ export const MainContent = styled.div({
7174
letterSpacing: '-0.012em',
7275
},
7376
code: { fontFamily: 'var(--ff-code)' },
77+
'pre[data-language]': {
78+
position: 'relative',
79+
'&::after': {
80+
position: 'absolute',
81+
top: 5,
82+
right: 10,
83+
opacity: 0.5,
84+
fontSize: '0.8rem',
85+
content: 'attr(data-language)',
86+
},
87+
},
7488
':not(pre) > code': {
7589
marginLeft: '1px',
7690
marginRight: '1px',
@@ -105,7 +119,7 @@ export const MainContent = styled.div({
105119
whiteSpace: 'pre',
106120
color: 'var(--gray-text-1)',
107121
border: '1px solid var(--gray-outline-2)',
108-
borderRadius: '12px',
122+
borderRadius: 8,
109123
},
110124
kbd: {
111125
padding: '6px',

0 commit comments

Comments
 (0)