docs: add some info into readmes

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/

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.