Docs: New documentation for Monorepo

master-co · May 24, 2024 · 12e27d2 · 12e27d2
1 parent 8fb681a
commit 12e27d2
Show file tree

Hide file tree

Showing 16 changed files with 145 additions and 50 deletions.
diff --git a/website/app/[locale]/guide/content.mdx b/website/app/[locale]/guide/content.mdx
@@ -1,28 +1,20 @@
 import guideCategories from '~/data/guide-categories.json'
 
----
-
 ## Getting Started
 <OverviewButtons>
     {guideCategories.find(category => category.name === 'Getting Started').pages}
 </OverviewButtons>
 
----
-
 ## Syntax Tutorial
 <OverviewButtons>
     {guideCategories.find(category => category.name === 'Syntax Tutorial').pages}
 </OverviewButtons>
 
----
-
 ## Fundamentals
 <OverviewButtons>
     {guideCategories.find(category => category.name === 'Fundamentals').pages}
 </OverviewButtons>
 
----
-
 ## Production Optimization
 <OverviewButtons>
     {guideCategories.find(category => category.name === 'Production Optimization').pages}

diff --git a/website/app/[locale]/guide/introduction/content.mdx b/website/app/[locale]/guide/introduction/content.mdx
@@ -33,7 +33,14 @@ Is the framework you're using not mentioned above? Check out the official [insta
 ## Why Master CSS?
 The reasons why to use Master CSS with an overview of features, syntax benefits, benchmarks, and a comprehensive comparison:
 
-### Rendering Modes
+### Minimal CSS Output
+This is a real-world benchmark of [critical CSS](https://web.dev/articles/codelab-extract-and-inline-critical-css) on page load for well-known official documentation websites.
+<CriticalCSSForDocsSitesBenchmark />
+According to HTTP Archive [CSS Bytes](https://httparchive.org/reports/page-weight#bytesCss), the sum of transfer size kilobytes of all external stylesheets requested by the page is **~82 kB**, excluding internal and inline styles.
+
+Master CSS only injects the CSS required by the page, so the official documentation site is super tiny, about **~6 kB per page** (brotli).
+{/* Reducing [critical CSS](https://web.dev/articles/codelab-extract-and-inline-critical-css) can improve page loading speed, browser rendering performance, and SEO metrics. */}
+
 Master CSS provides three [rendering modes](/guide/rendering-modes), and you can choose according to project scale and application scenarios to meet your business needs.
 
 One of the most unique, the [progressive rendering](/guide/rendering-modes/progressive-rendering) works by pre-rendering the critical CSS based on the element's class names and deferring the loading of the runtime engine for any future dynamic class names.
@@ -42,21 +49,30 @@ One of the most unique, the [progressive rendering](/guide/rendering-modes/progr
 <html lang="en">
 <head>
     …
-+    <style id="master">.block{display:block}</style>
+    <!-- Generate only the critical CSS required for the page. -->
+    <style id="master">
++       .block {
++           display: block
++       }
+    </style>
     <script src="https://cdn.master.co/css-runtime@rc" defer></script>
 </head>
 <body>
     <h1 class="**block**">Hello World</h1>
 </body>
 </html>
 ```
-This ensures the page generates the [ultra-lightweight CSS](#minimal-css-on-the-market) and the fastest first-page render, unlike traditionally bundling styles across the entire application.
+This ensures the page generates the ultra-lightweight CSS and the fastest first-page render, unlike traditionally bundling styles across the entire application.
+
+Initially, Master CSS was intended to create a CSS engine for production browser runtimes, so we concentrated on performance such as syntax parsing, rule generation, cache sharing, and even browser rendering.
+
+Master CSS doesn't use heavy-duty build tools like PostCSS, Autoprefixer, or any minifiers, as these rules are generated with optimization.
 
-### Design System APIs
+### Custom Design Systems
 Master CSS provides a set of systematic [configuration](/reference/configuration) APIs to help you build a consistent, easy-to-manage, and scalable design system:
 <Configuration />
 
-We have built a series of neutral tokens in the default configuration and created a universal Master Design System, which make your design system on top of or use it as a quick starting point.
+We've built a series of neutral tokens in the default configuration and created a universal Master Design System, which make your design system on top of or use it as a quick starting point.
 <DesignVariables />
 This is just one part; more design variables and tokens are scattered throughout the syntax documentation.
 
@@ -70,7 +86,7 @@ For example, the utility class `capitalize` is used to simplify `css text-transf
 <p class="**capitalize**">Heavy boxes perform quick waltzes and jigs.</p>
 ```
 
-### Syntax Highlighting
+### Innovative Syntax Highlighting
 Master CSS is the first language to highlight class names fully, making identifying their properties, appearance, and state faster.
 
 (!) Do you find writing utility classes sometimes seem lengthy or hard to read?
@@ -89,7 +105,7 @@ Master CSS is the first language to highlight class names fully, making identify
 </Demo>
 This feature is included in the [Master CSS Language Service](/guide/language-service).
 
-### Code Linting
+### Reliable Code Linting
 Have you ever felt anxious about adding styles to class attributes? Master CSS was the first to introduce [syntax validation](/guide/code-linting#syntax-error-checks) of classes in template markup, which helps you find errors early before building and dramatically improves the developer experience.
 <Image className="aspect:2/1 r:2x max-w:screen-xs w:full" src={require('~/public/syntax-error-checks.webp').default} alt="Syntax error checks" unoptimized />
 
@@ -101,18 +117,6 @@ This is just a piece of cake; we also allow you to **enforce consistent class or
 
 To learn more, check out the [Code Linting](/guide/code-linting) documentation.
 
-### Minimal CSS on the market
-Initially, Master CSS was intended to create a CSS engine for production browser runtimes, so we concentrated on performance such as syntax parsing, rule generation, cache sharing, and even browser rendering.
-
-Master CSS doesn't use heavy-duty build tools like PostCSS, Autoprefixer, or any minifiers, as these rules are generated with optimization.
-
-This is a real-world benchmark of [critical CSS](https://web.dev/articles/codelab-extract-and-inline-critical-css) on page load for well-known official documentation websites.
-<CriticalCSSForDocsSitesBenchmark />
-According to HTTP Archive [CSS Bytes](https://httparchive.org/reports/page-weight#bytesCss), the sum of transfer size kilobytes of all external stylesheets requested by the page is **~82 kB**, excluding internal and inline styles.
-
-Master CSS only injects the CSS required by the page, so the official documentation site is super tiny, about **~6 kB per page** (brotli).
-{/* Reducing [critical CSS](https://web.dev/articles/codelab-extract-and-inline-critical-css) can improve page loading speed, browser rendering performance, and SEO metrics. */}
-
 ### Comparisons
 Here’s a comprehensive comparison of Master CSS, Tailwind CSS and Bootstrap:
 <Comparisons />

diff --git a/website/app/[locale]/guide/language-service/content.mdx b/website/app/[locale]/guide/language-service/content.mdx
@@ -12,4 +12,4 @@ import brands from 'websites/data/brands'
 ---
 
 ## Features
-### Syntax Highlighting
+🚧
diff --git a/website/app/[locale]/guide/migration/metadata.ts b/website/app/[locale]/guide/migration/metadata.ts
@@ -8,8 +8,7 @@ const metadata: Metadata = {
     category: 'Getting Started',
     other: {
         subject: 'Migration'
-    },
-    order: 5
+    }
 }
 
 export default metadata
diff --git a/website/app/[locale]/guide/monorepo/_opengraph-image.tsx b/website/app/[locale]/guide/monorepo/_opengraph-image.tsx
@@ -0,0 +1,13 @@
+import { Props } from 'websites/types/Props'
+import create from '~/og-image'
+import metadata from './metadata'
+import type { AbsoluteTemplateString } from 'next/dist/lib/metadata/types/metadata-types'
+
+export const alt = (metadata.title as AbsoluteTemplateString)?.absolute || metadata.title as string
+export const contentType = 'image/jpg'
+export const runtime = 'nodejs'
+
+export default (props: Props) => create({
+    props,
+    metadata
+})
diff --git a/website/app/[locale]/guide/monorepo/content.mdx b/website/app/[locale]/guide/monorepo/content.mdx
@@ -0,0 +1,64 @@
+## Foreword [sr-only]
+The Master CSS [Language Server](/reference/language-server) and [ESLint plugin](/reference/eslint) both support the monorepo development strategy.
+
+By default, the language server will form independent workspaces based on the location of the __master.css.*__ configuration files, independent of the package manager's workspace. The same goes for ESLint, which forms a new working directory based on the location of its configuration file.
+
+Officially integrated packages or extensions will automatically read the __master.css.*__ configuration based on the current running directory. This means that you can start using it with zero configuration as long as you create a configuration file in the workspace.
+
+---
+
+## One root master.css.js
+Whether it's a single repository or a monorepo, create a __master.css.js__ file in the root directory for your design system.
+```treeview
+🗂️ src
+📄 eslint.config.js
+📄 master.css.js
+```
+The language service will create at least a root workspace regardless of whether `master.css.*` exists.
+
+---
+
+## One master.css.js per microservice
+When there are different design systems or complex requirements in a monorepo, you may need to create __master.css.js__ and __eslint.config.js__ for multiple folders.
+
+(i) This will create two workspaces, `/` and `/apps/a`.
+```treeview
+🗂️ apps
+|-- 🗂️ a
+|   |-- 📄 eslint.config.js
+|   `-- 📄 master.css.js
+`-- 🗂️ b
+📄 eslint.config.js
+📄 master.css.js
+```
+Note that `/apps/b` will be considered part of the root workspace `/`.
+
+### Shared the configuration
+In each workspace, you need to export the common root configuration.
+```ts name=apps/a/master.css.js
+export { default } from '../../master.css'
+```
+Or extend it and add workspace-specific customization options.
+```ts name=apps/a/master.css.js
+import common from '../../master.css'
+
+export default {
+    extends: [
+        common
+    ],
+    ...
+}
+```
+Regardless of whether there is a specific workspace configuration, exporting the configuration is necessary when the workspace exists in __eslint.config.js__.
+
+(x) Forgot to create __/apps/a/master.css.js__ in the workspace and export the root configuration.
+```treeview
+🗂️ apps
+|-- 🗂️ a
+|   |-- 📄 eslint.config.js
+-|   `-- 📄 master.css.js
+`-- 🗂️ b
+📄 eslint.config.js
+📄 master.css.js
+```
+Unless this workspace is not using Master CSS, this is a common oversight.
diff --git a/website/app/[locale]/guide/monorepo/metadata.ts b/website/app/[locale]/guide/monorepo/metadata.ts
@@ -0,0 +1,9 @@
+import { Metadata } from 'websites/types/Metadata'
+
+const metadata: Metadata = {
+    title: 'Monorepo',
+    description: 'A guide to setting up Master CSS in a modern repository.',
+    category: 'Development Strategy'
+}
+
+export default metadata
diff --git a/website/app/[locale]/guide/monorepo/page.tsx b/website/app/[locale]/guide/monorepo/page.tsx
@@ -0,0 +1,21 @@
+import Layout from '~/layouts/doc'
+import pageCategories from '~/data/guide-categories.json'
+import metadata from './metadata'
+/* @ts-expect-error toc */
+import Content, { toc } from './content.mdx'
+import { generate } from '~/utils/metadata'
+
+export const dynamic = 'force-static'
+export const revalidate = false
+
+export async function generateMetadata(props: any, parent: any) {
+    return await generate(metadata, props, parent)
+}
+
+export default async function Page(props: any) {
+    return (
+        <Layout {...props} pageCategories={pageCategories} pageDirname={__dirname} metadata={metadata} toc={toc} >
+            <Content />
+        </Layout >
+    )
+}
diff --git a/website/app/[locale]/guide/responsive-design/metadata.ts b/website/app/[locale]/guide/responsive-design/metadata.ts
@@ -3,7 +3,7 @@ import { Metadata } from 'websites/types/Metadata'
 const metadata: Metadata = {
     title: 'Responsive Design',
     description: 'Adapt your user interface to different devices with flexible responsive syntax.',
-    category: 'Fundamentals',
+    category: 'Development Strategy',
     order: 5
 }
 

diff --git a/website/app/[locale]/guide/reusing-styles/metadata.ts b/website/app/[locale]/guide/reusing-styles/metadata.ts
@@ -2,8 +2,8 @@ import { Metadata } from 'websites/types/Metadata'
 
 const metadata: Metadata = {
     title: 'Reusing Styles',
-    description: 'This guide helps develop concepts for code reuse and de-duplication techniques.',
-    category: 'Fundamentals',
+    description: 'A guide to reusing styles and code de-duplication.',
+    category: 'Development Strategy',
     disabled: true
 }
 

diff --git a/website/app/[locale]/guide/variables-and-modes/metadata.ts b/website/app/[locale]/guide/variables-and-modes/metadata.ts
@@ -3,7 +3,7 @@ import { Metadata } from 'websites/types/Metadata'
 const metadata: Metadata = {
     title: 'Theme Modes and Variables',
     description: 'Use design tokens to switch between different theme modes.',
-    category: 'Fundamentals',
+    category: 'Development Strategy',
     disabled: true,
     other: {
         subject: 'Variables & Modes'

diff --git a/website/app/[locale]/reference/content.mdx b/website/app/[locale]/reference/content.mdx
@@ -1,28 +1,20 @@
 import referenceCategories from '~/data/reference-categories.json'
 
----
-
 ## Variable
 <OverviewButtons>
     {referenceCategories.find(category => category.name === 'Variable').pages}
 </OverviewButtons>
 
----
-
 ## Configuration
 <OverviewButtons>
     {referenceCategories.find(category => category.name === 'Configuration').pages}
 </OverviewButtons>
 
----
-
 ## Syntax
 <OverviewButtons>
     {referenceCategories.find(category => category.name === 'Syntax').pages}
 </OverviewButtons>
 
----
-
 ## Package
 <OverviewButtons>
     {referenceCategories.find(category => category.name === 'Package').pages}

diff --git a/website/app/[locale]/reference/styles/content.mdx b/website/app/[locale]/reference/styles/content.mdx
@@ -68,10 +68,10 @@ You can see that `b` inherits the text lime color of `a`:
 Whether to split into multiple files depends on how many abstract styles you have.
 ```treeview
 project/
-|-- styles
-|   |-- btn.css.js
-|   `-- card.css.js
-`-- master.css.js
+|-- 🗂️ styles
+|   |-- 📄 btn.css.js
+|   `-- 📄 card.css.js
+`-- 📄 master.css.js
 ```
 Typically, frameworks or standard directory structures come with a "styles/" folder for CSS files, and we recommend placing your custom styles there with "styles/*.css.js".
 ```js name=styles/btn.css.js

diff --git a/website/categories.json b/website/categories.json
@@ -4,6 +4,7 @@
     "Getting Started",
     "Syntax Tutorial",
     "Fundamentals",
+    "Development Strategy",
     "Production Optimization",
 
     "Variable",

diff --git a/website/components/OverviewButtons.tsx b/website/components/OverviewButtons.tsx
@@ -15,8 +15,8 @@ export default ({ children, className, url }: any) =>
                 href={page.pathname}
                 disabled={page.metadata?.disabled}
                 rel="noreferrer noopener">
-                <div className='text:18'>{((page.metadata.title as any)?.absolute || page.metadata.title) as string}</div>
-                <div className='text:14 fg:light lines:2'>{page.metadata.description as string}</div>
+                <div className='font:16 leading:1.6 font:semibold'>{((page.metadata.title as any)?.absolute || page.metadata.title) as string}</div>
+                <div className='fg:light lines:2 text:12 mt:1x'>{page.metadata.description as string}</div>
             </Link>
         )
     }</div >
diff --git a/website/links.tsx b/website/links.tsx
@@ -1,8 +1,8 @@
-import { IconFileText, IconRoad, IconSourceCode } from '@tabler/icons-react'
+import { IconCompass, IconFileText, IconRoad, IconSourceCode } from '@tabler/icons-react'
 import roadmap from './app/[locale]/roadmap/metadata'
 
 const links = [
-    { name: 'Guide', href: '/guide', Icon: IconFileText },
+    { name: 'Guide', href: '/guide', Icon: IconCompass },
     { name: 'Reference', fullName: 'API Reference', href: '/reference', Icon: IconFileText },
     { name: 'Play', href: '/play', Icon: IconSourceCode },
     { name: 'Roadmap', href: '/roadmap', Icon: IconRoad, date: roadmap.date },