From 12e27d2c5aa36cb6a4b4d83721651d6ade18529c Mon Sep 17 00:00:00 2001 From: Aron Date: Fri, 24 May 2024 16:28:19 +0800 Subject: [PATCH] Docs: New documentation for Monorepo --- website/app/[locale]/guide/content.mdx | 8 --- .../[locale]/guide/introduction/content.mdx | 42 ++++++------ .../guide/language-service/content.mdx | 2 +- .../app/[locale]/guide/migration/metadata.ts | 3 +- .../guide/monorepo/_opengraph-image.tsx | 13 ++++ .../app/[locale]/guide/monorepo/content.mdx | 64 +++++++++++++++++++ .../app/[locale]/guide/monorepo/metadata.ts | 9 +++ website/app/[locale]/guide/monorepo/page.tsx | 21 ++++++ .../guide/responsive-design/metadata.ts | 2 +- .../[locale]/guide/reusing-styles/metadata.ts | 4 +- .../guide/variables-and-modes/metadata.ts | 2 +- website/app/[locale]/reference/content.mdx | 8 --- .../app/[locale]/reference/styles/content.mdx | 8 +-- website/categories.json | 1 + website/components/OverviewButtons.tsx | 4 +- website/links.tsx | 4 +- 16 files changed, 145 insertions(+), 50 deletions(-) create mode 100644 website/app/[locale]/guide/monorepo/_opengraph-image.tsx create mode 100644 website/app/[locale]/guide/monorepo/content.mdx create mode 100644 website/app/[locale]/guide/monorepo/metadata.ts create mode 100644 website/app/[locale]/guide/monorepo/page.tsx diff --git a/website/app/[locale]/guide/content.mdx b/website/app/[locale]/guide/content.mdx index fd1b18aa9..c315bdf6c 100644 --- 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 {guideCategories.find(category => category.name === 'Getting Started').pages} ---- - ## Syntax Tutorial {guideCategories.find(category => category.name === 'Syntax Tutorial').pages} ---- - ## Fundamentals {guideCategories.find(category => category.name === 'Fundamentals').pages} ---- - ## Production Optimization {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 index 2485814c3..cde461905 100644 --- 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. + +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,7 +49,12 @@ One of the most unique, the [progressive rendering](/guide/rendering-modes/progr … -+ + + @@ -50,13 +62,17 @@ One of the most unique, the [progressive rendering](/guide/rendering-modes/progr ``` -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: -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. 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

Heavy boxes perform quick waltzes and jigs.

``` -### 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 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. Syntax error checks @@ -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. - -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: diff --git a/website/app/[locale]/guide/language-service/content.mdx b/website/app/[locale]/guide/language-service/content.mdx index f901a3740..d628c61cc 100644 --- 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 \ No newline at end of file +🚧 diff --git a/website/app/[locale]/guide/migration/metadata.ts b/website/app/[locale]/guide/migration/metadata.ts index 9817fb72b..9a33d29d2 100644 --- 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 \ No newline at end of file diff --git a/website/app/[locale]/guide/monorepo/_opengraph-image.tsx b/website/app/[locale]/guide/monorepo/_opengraph-image.tsx new file mode 100644 index 000000000..e91f5b6f8 --- /dev/null +++ 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 +}) \ No newline at end of file diff --git a/website/app/[locale]/guide/monorepo/content.mdx b/website/app/[locale]/guide/monorepo/content.mdx new file mode 100644 index 000000000..8c02377ba --- /dev/null +++ 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. \ No newline at end of file diff --git a/website/app/[locale]/guide/monorepo/metadata.ts b/website/app/[locale]/guide/monorepo/metadata.ts new file mode 100644 index 000000000..4dc39a7ae --- /dev/null +++ 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 \ No newline at end of file diff --git a/website/app/[locale]/guide/monorepo/page.tsx b/website/app/[locale]/guide/monorepo/page.tsx new file mode 100644 index 000000000..06f57ee88 --- /dev/null +++ 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 ( + + + + ) +} \ No newline at end of file diff --git a/website/app/[locale]/guide/responsive-design/metadata.ts b/website/app/[locale]/guide/responsive-design/metadata.ts index ff19e56e9..40b23e52c 100644 --- 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 index 2b4cd003f..736c42797 100644 --- 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 index 1d66ce0ea..4baabcc04 100644 --- 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 index 7cea5b18e..ae358c030 100644 --- 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 {referenceCategories.find(category => category.name === 'Variable').pages} ---- - ## Configuration {referenceCategories.find(category => category.name === 'Configuration').pages} ---- - ## Syntax {referenceCategories.find(category => category.name === 'Syntax').pages} ---- - ## Package {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 index 971ec8c5c..a916dc130 100644 --- 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 index 01143e803..a089ca3fa 100644 --- 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 index 65598732d..52e9c93a3 100644 --- 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"> -
{((page.metadata.title as any)?.absolute || page.metadata.title) as string}
-
{page.metadata.description as string}
+
{((page.metadata.title as any)?.absolute || page.metadata.title) as string}
+
{page.metadata.description as string}
) } \ No newline at end of file diff --git a/website/links.tsx b/website/links.tsx index eb057a810..6d271c00c 100644 --- 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 },