[docs] Setup a new next.js application for documentation (#299)

Co-authored-by: Brijesh Bittu <brijesh42@gmail.com>

.eslintignore

@@ -5,6 +5,7 @@
 /docs/pages/playground/
 /packages/pigment-css-react/utils/
 /packages/pigment-css-react/processors/
+/packages/pigment-css-react/internal/
 /packages/pigment-css-react/exports/
 /packages/pigment-css-react/theme/
 /packages/pigment-css-react/tests/**/fixtures

.eslintrc.js

@@ -43,6 +43,7 @@ module.exports = {
    */
   rules: {
     'consistent-this': ['error', 'self'],
+    'import/prefer-default-export': 'off',
     curly: ['error', 'all'],
     // Just as bad as "max components per file"
     'max-classes-per-file': 'off',

.gitignore

@@ -9,7 +9,7 @@
 !.vscode/extensions.json
 *.log
 *.tsbuildinfo
-/.eslintcache
+.eslintcache
 /.nyc_output
 /benchmark/**/dist
 /coverage

docs/.eslintrc.js

@@ -0,0 +1,18 @@
+module.exports = {
+  rules: {
+    'react/prop-types': 'off',
+    'react/react-in-jsx-scope': 'off',
+    'react/no-unknown-property': ['error', { ignore: ['sx'] }],
+    'import/extensions': [
+      'error',
+      'ignorePackages',
+      {
+        '': 'never',
+        js: 'never',
+        jsx: 'never',
+        ts: 'never',
+        tsx: 'never',
+      },
+    ],
+  },
+};

docs/.gitignore

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (can opt-in for commiting if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

docs/README.md

@@ -0,0 +1,4 @@
+# Pigment CSS Docs app
+
+This is the Pigment CSS docs application bootstrapped with Next.js 15. It uses app router and
+Pigment CSS for styling.

docs/data/getMarkdownPage.ts

@@ -0,0 +1,87 @@
+import * as path from 'path';
+import * as fs from 'node:fs/promises';
+import { evaluate } from '@mdx-js/mdx';
+import * as jsxRuntime from 'react/jsx-runtime';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
+import remarkGfm from 'remark-gfm';
+import rehypeSlug from 'rehype-slug';
+import extractToc, { type Toc } from '@stefanprobst/rehype-extract-toc';
+import exportToc from '@stefanprobst/rehype-extract-toc/mdx';
+import { read as readVFile } from 'to-vfile';
+import { matter } from 'vfile-matter';
+
+export interface PageMetadata {
+  title: string;
+  description: string;
+  components?: string;
+  githubLabel?: string;
+  slug: string;
+}
+
+async function getFileHandle(basePath: string, slug: string) {
+  const mdxFilePath = path.join(process.env.DATA_DIR as string, basePath, slug, `${slug}.mdx`);
+  const mdFilePath = path.join(process.env.DATA_DIR as string, basePath, slug, `${slug}.md`);
+
+  try {
+    const fileHandle = await fs.open(mdxFilePath);
+    return {
+      handle: fileHandle,
+      path: mdxFilePath,
+      [Symbol.asyncDispose]: async () => {
+        await fileHandle.close();
+      },
+    };
+  } catch (ex1) {
+    try {
+      const fileHandle = await fs.open(mdFilePath);
+      return {
+        handle: fileHandle,
+        path: mdFilePath,
+        [Symbol.asyncDispose]: async () => {
+          await fileHandle.close();
+        },
+      };
+    } catch (ex2) {
+      throw new Error('404');
+    }
+  }
+}
+
+export async function getMarkdownPage(basePath: string, slug: string) {
+  await using file = await getFileHandle(basePath, slug);
+  const mdxSource = await file.handle.readFile({
+    encoding: 'utf-8',
+  });
+  const {
+    default: MDXContent,
+    frontmatter,
+    tableOfContents,
+  } = await evaluate(mdxSource, {
+    ...jsxRuntime,
+    remarkPlugins: [remarkGfm, remarkFrontmatter, remarkMdxFrontmatter],
+    rehypePlugins: [
+      // [rehypePrettyCode, { theme: config.shikiThemes }],
+      rehypeSlug,
+      extractToc,
+      exportToc,
+    ],
+  });
+
+  return {
+    metadata: {
+      ...(frontmatter as Partial<PageMetadata>),
+      slug,
+    } as PageMetadata,
+    tableOfContents: tableOfContents as Toc,
+    MDXContent,
+  };
+}
+
+export async function getMarkdownPageMetadata(basePath: string, slug: string) {
+  await using file = await getFileHandle(basePath, slug);
+
+  const vfile = await readVFile(file.path);
+  matter(vfile);
+  return vfile.data.matter as PageMetadata;
+}

docs/data/getting-started/overview/overview.mdx

@@ -0,0 +1,12 @@
+---
+title: Quick start
+description: Get started with Pigment CSS, a zero-runtime CSS-in-JS library.
+---
+
+# Quick start
+
+<Description />
+
+## Installation
+
+Pigment CSS has two category of packages. First one is to be imported and used in your source code. This includes the public API of the package. Second category is to be imported in your bundler config file to configure and actually be able to use Pigment CSS. We currently support [`Next.js`](https://nextjs.org/) (no Turbopack yet), [`Vite`](https://vite.dev/) and [`Webpack`](https://webpack.js.org/).

docs/data/pages.ts

@@ -0,0 +1,36 @@
+export interface RouteMetadata {
+  pathname: string;
+  title?: string;
+  children?: readonly RouteMetadata[];
+  planned?: boolean;
+  unstable?: boolean;
+}
+
+const pages: readonly RouteMetadata[] = [
+  {
+    pathname: '/getting-started',
+    title: 'Getting started',
+    children: [{ pathname: '/getting-started/overview', title: 'Overview' }],
+  },
+];
+
+export default pages;
+
+function extractSlug(pathname: string) {
+  return pathname.split('/').pop()!;
+}
+
+export function getSlugs(parentPath: string) {
+  const slugs: string[] = [];
+
+  const categoryPages = pages.find((page) => page.pathname === parentPath);
+  categoryPages?.children?.forEach((level2Page) => {
+    if (level2Page.children) {
+      slugs.push(...level2Page.children.map((page) => extractSlug(page.pathname)));
+    } else {
+      slugs.push(extractSlug(level2Page.pathname));
+    }
+  });
+
+  return slugs;
+}

docs/next.config.ts

@@ -0,0 +1,33 @@
+import type { NextConfig } from 'next';
+import { withPigment, extendTheme } from '@pigment-css/nextjs-plugin';
+import path from 'path';
+import { theme as baseTheme } from './src/theme';
+
+const DATA_DIR = path.join(process.cwd(), 'data');
+
+const nextConfig: NextConfig = {
+  trailingSlash: false,
+  env: {
+    DATA_DIR,
+  },
+  distDir: 'export',
+  output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+};
+
+const theme = extendTheme({
+  colorSchemes: {
+    light: baseTheme,
+  },
+});
+
+export default withPigment(nextConfig, {
+  theme,
+  displayName: true,
+  sourceMap: true,
+  babelOptions: {
+    plugins: ['@babel/plugin-proposal-explicit-resource-management'],
+  },
+});

docs/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "docs",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "cross-env NODE_ENV=production next build",
+    "preview": "serve ./export",
+    "lint": "next lint",
+    "typescript": "tsc --noEmit -p ."
+  },
+  "dependencies": {
+    "@base_ui/react": "^1.0.0-alpha.3",
+    "@mdx-js/mdx": "^3.1.0",
+    "@pigment-css/react": "workspace:*",
+    "@stefanprobst/rehype-extract-toc": "^2.2.0",
+    "clsx": "^2.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "next": "15.0.2",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-mdx-frontmatter": "^5.0.0",
+    "to-vfile": "^8.0.0",
+    "vfile-matter": "^5.0.0"
+  },
+  "devDependencies": {
+    "@babel/plugin-proposal-explicit-resource-management": "^7.25.9",
+    "@pigment-css/nextjs-plugin": "workspace:*",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "eslint-config-next": "15.0.2",
+    "serve": "14.2.4",
+    "tailwindcss": "^3.4.14"
+  },
+  "nx": {
+    "targets": {
+      "typescript": {
+        "cache": false,
+        "dependsOn": [
+          "^build"
+        ]
+      },
+      "build": {
+        "outputs": [
+          "{projectRoot}/.next",
+          "{projectRoot}/export"
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { MainContent } from '@/components/MainContent';
+
+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>
+  );
+}