From 925ebb7147d133d75e57f95c125c5ff57587fc3c Mon Sep 17 00:00:00 2001 From: Mikkel Laursen Date: Sat, 11 Nov 2023 10:25:18 -0500 Subject: [PATCH] docs: add some info into readmes --- README.md | 19 ++++++--- apps/docs/README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ad91cfd57b..efc1a989b4 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,20 @@ [![npm](https://img.shields.io/npm/v/react-md)](https://www.npmjs.com/package/react-md) [![downloads](https://img.shields.io/npm/dw/react-md)](https://www.npmjs.com/package/react-md) -Create an accessible React application with the -[material design specifications](https://material.io/design/) and SCSS. +Create an accessible React application with the [material design specifications] +and SCSS. -## [Full Documentation (Preview)](https://next.react-md.dev) +## [Installation] + +```sh +npm install @react-md/core sass +``` + +## [Full Documentation (Preview)] ### Highlights/Features -- Matches the accessibility guidelines from [www.w3.org](https://www.w3.org/TR/wai-aria-practices) +- Matches the accessibility guidelines from [www.w3.org] - Low level customizable components - Easily themeable on a global and component level - Uses css variables for dynamic themes with fallbacks for older browsers @@ -24,4 +30,7 @@ Please read the [contributing guidelines](./.github/CONTRIBUTING.md) if you would like to contribute. [typescript]: https://www.typescriptlang.org/ -[create-react-app]: https://facebook.github.io/create-react-app +[www.w3.org]: https://www.w3.org/TR/wai-aria-practices +[installation]: https://next.react-md.dev/getting-started/installation +[full documentation (preview)]: https://next.react-md.dev +[material design specifications]: https://material.io/design/ diff --git a/apps/docs/README.md b/apps/docs/README.md index d908fbeef9..9c770e7b30 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -1 +1,102 @@ # react-md Documentation Website + +The documentation website for react-md hosted at https://react-md.dev. Previews +of the next version are available at https://next.react-md.dev. + +## Commands + +- `create-env` - Generates a `.env.local` file with some metadata + environment variables that supports vercel and local development. +- `mdx-pages` - Generates all the `.mdx` pages throughout the app. +- `scss-lookup` - Generates the `src/constants/scssLookup.ts` file. +- `prism-themes` - Generates all the `.module.scss` files for all the prism themes + and the code that lazy loads it based on user preference. +- `watch` - Runs all the development watchers and starts the development server. + - `watch-mdx-pages` - Only watch for MDX page changes. + - `watch-scss-lookup` - Only watch for `@react-md/core` scss changes. +- `clean` - Removes all the generated files and dependencies. + - `clean-static` - Removes the `.turbo`, `.next`, and `node_modules` + directories. + - `clean-api-docs` - Only cleans the generated api docs. + - `clean-mdx-pages` - Only cleans the generated MDX pages. +- `lint` - Runs all the linters. + - `lint-scripts` - Runs `eslint` against all `.ts`, `.tsx`, `.js`, `.jsx` + files. + - `lint-styles` - Runs `stylelint` against all `.css` and `.scss` files. +- `typecheck` + - `typecheck-src` - Only runs the type checker in the `src` directory. + - `typecheck-scripts` - Only runs the type checker in the `scripts` directory. +- `dev` - Starts all the development watchers and the development server + - `next-dev` - Only starts the development server. +- `build` - Regenerates all the code and builds the production Website. + - `next-build` - Only builds the production website. +- `start` - Starts the production website. + +## Component Demos + +The development workflow is: + +- Start the dev server and all watchers with `pnpm --filter docs dev` + - Or if you want to split things out into different terminal tabs + - `pnpm --filter docs next-dev` + - `pnpm --filter docs watch` +- Make changes to `demos.mdx` or any demo component related file. +- The `demo-page.mdx`, `page.tsx`, and `toc.ts` files will automatically be + re-generated whenever a file is saved. + +Do not modify the `page.tsx`, `demos-page.mdx`, or `toc.ts` files in the +component directories since they are generated by the `demos.mdx` file. Only +make changes to `demos.mdx` and any component related demo files. + +What happens behind the scenes is: + +- Parse the contents of the `demos.mdx` to find JSON for loading code + - `{{ "component": "./SimpleExample.tsx" }}` + - Check out + [ParsedOptions](./scripts/utils/createDemoMarkdown.ts#L11-19) for + other available properties +- Use [ts-morph](https://github.com/dsherret/ts-morph) to combine all imports + into the same file and find any SCSS Modules required for the demo +- Create a "fake scss module" for any that were found that includes the + pre-compiled `css` and the full `scss` contents +- Generate a `demo-page.mdx` that replaces all the JSON code references with the + resolved code snippets +- Parse the contents of the `demos-page.mdx` to create a table of contents +- Generate a `toc.ts` with the table of contents data +- Generate a `page.tsx` that imports the `demo-page.mdx` and the table of + contents and renders everything in a `MarkdownPage`. This will also generate + the correct `metadata` for the page. + +I was hoping I'd be able to use one of the Next.js route features to handle this, +but I ran into a few issues: + +- You can't really dynamically load MDX files (or at least the time of writing + this) + - You can't really use `node:fs` in RSC. Most files don't exist once deployed + to vercel. +- You can't try to work around this by creating an API that dynamically loads it + for you since local API functions are not available at build time +- Since the `RootLayout` for this app accesses cookies for things like color + scheme, prism theme, etc, most pages are still run in production instead of + build time only + +## Other MDX Pages + +When making an update to other MDX pages, modify the `README.mdx`. This will +start the following flow: + +- Parse the contents of the `README.mdx` to create a table of contents +- Generate a `toc.ts` with the table of contents data +- Generate a `page.tsx` that imports the `README.mdx` and the table of contents + and renders everything in a `MarkdownPage`. This will also generate the + correct `metadata` for the page. + +### create-env + +Generates a `.env.local` file that defines all the environment variables +required to run the documentation website. + +When run during a vercel deployment, it will attempt to get the current `git` +metadata through the available [framework environment variables](https://vercel.com/docs/projects/environment-variables/system-environment-variables#framework-environment-variables). + +When run locally, it will use the current git branch and commit metadata.