Improve README and new contributor experience (#158)

* Make GH_TOKEN optional

* Improve README for contributors

README.md

@@ -1,8 +1,17 @@
 # React Router Website!
 
+## Contributing
+
+If you want to make a contribution
+
+- [Fork and clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repo
+- Create a branch
+- Push any changes you make to your branch
+- Open up a PR in this Repo
+
 ## Setup
 
-Copy the contents of `.env.example` file to the `.env` file and add your information to it.
+First setup your `.env` file, use `.env.example` to know what to set.
 
 ```sh
 cp .env.example .env
@@ -11,34 +20,70 @@ cp .env.example .env
 Install dependencies
 
 ```sh
-npm install
+npm i
 ```
 
-That's it!
+## Local Development
 
-## Development
+Now you should be good to go:
 
 ```sh
 npm run dev
 ```
 
-There are a couple LRUCache's for talking to GitHub and processing markdown that expire after 5 minutes, if you want them to expire immediately for local development, set the `NO_CACHE` environment variable.
+To preview local changes to the `docs` folder in the React Router repo, select "local" from the version dropdown menu on the site. Make sure you have the [react-router repo](https://github.com/remix-run/react-router) cloned locally and `LOCAL_REPO_RELATIVE_PATH` is pointed to the correct filepath.
+
+We leverage a number of LRUCache's to server-side cache various resources, such as processed markdown from GitHub, that expire at various times (usually after 5 minutes). If you want them to expire immediately for local development, set the `NO_CACHE` environment variable.
 
 ```sh
 NO_CACHE=1 npm run dev
 ```
 
-To work on local docs clone the react router repo and put it in the same folder as this website repo:
+Note that by default this assumes the relative path to your local copy of the React Router docs is `../react-router`. This can be configured via `LOCAL_REPO_RELATIVE_PATH` in your `.env` file.
 
+## Preview
+
+To preview the production build locally:
+
+```sh
+npm run build
+npm run preview
 ```
-~/ur-stuff/reactrouter-website
-~/ur-stuff/react-router
-```
 
-Then point `.env` at it like this:
+## Deployment
+
+The production server is always in sync with `main`
 
+```sh
+git push origin main
+open https://reactrouter.com
 ```
-LOCAL_REPO_RELATIVE_PATH="../react-router"
+
+Pushing the "stage" tag will deploy to [staging](https://reactrouterdotcomstaging.fly.dev/).
+
+```sh
+git checkout my/branch
+
+# moves the `stage` tag and pushes it, triggering a deploy
+npm run push:stage
 ```
 
-You'll notice a "local" option in the version dropdown menu when the app is running. That will pull the docs from your machine instead of GitHub.
+When you're happy with it, merge your branch into `main` and push.
+
+## CSS Notes
+
+You'll want the [tailwind VSCode plugin](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) fer sure, the hints are amazing.
+
+The color scheme has various shades but we also have a special "brand" rule for each of our brand colors so we don't have to know the specific number of that color like this: `<div className="text-pink-brand" />`.
+
+We want to use Tailwind's default classes as much as possible to avoid a large CSS file. A few things you can do to keep the styles shared:
+
+- Avoid changing anything but the theme in `tailwind.config.js`, no special classes, etc.
+- Avoid "inline rules" like `color-[#ccc]` as much as possible.
+- Silly HTML (like a wrapper div to add padding on a container) is better than one-off css rules.
+
+## Algolia Search
+
+We use [DocSearch](https://docsearch.algolia.com/) by Algolia for our documentation's search. The site is automatically scraped and indexed weekly by the [Algolia Crawler](https://crawler.algolia.com/).
+
+If the doc search results ever seem outdated or incorrect be sure to check that the crawler isn't blocked. If it is, it might just need to be canceled and restarted to kick things off again. There is also an editor in the Crawler admin that lets you adjust the crawler's script if needed.

app/modules/gh-docs/.server/github.ts

@@ -2,8 +2,15 @@ import { Octokit } from "octokit";
 
 const GH_TOKEN = process.env.GH_TOKEN!;
 
-if (process.env.NODE_ENV !== "test" && !GH_TOKEN) {
-  throw new Error("Missing GH_TOKEN");
+const env = process.env.NODE_ENV;
+
+if (env !== "test" && !GH_TOKEN) {
+  if (env === "production") {
+    throw new Error("No GH_TOKEN provided");
+  }
+  console.warn(
+    "\nNo GH_TOKEN provided. You can increase the rate limit from 60/hr to 1000/hr by adding a token to your .env file.\n"
+  );
 }
 
 const octokit = new Octokit({ auth: GH_TOKEN });

package.json

@@ -4,12 +4,12 @@
   "type": "module",
   "scripts": {
     "dev": "cross-env NODE_ENV=development node server.js",
-    "build": "react-router build",
+    "build": "cross-env NODE_ENV=development react-router build",
     "format": "prettier --write . && npm run lint:fix",
     "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
     "lint:fix": "npm run lint -- --fix",
-    "start": "node server.js",
-    "preview": "dotenv node server.js",
+    "start": "cross-env NODE_ENV=production node server.js",
+    "preview": "cross-env NODE_ENV=production dotenv node server.js",
     "test": "vitest",
     "typecheck": "react-router typegen && tsc",
     "push:stage": "git tag -f stage && git push origin stage -f"