Improve README and simplify .env.example (#159)

Author: brookslybrand

.env.example

@@ -1,10 +1,5 @@
-FLY_APP_NAME="remixdotrun"
-
-# Get from https://app.convertkit.com/account_settings/advanced_settings
-CONVERTKIT_KEY="..."
-
 # A token to increase the rate limiting from 60/hr to 1000/hr
-GITHUB_TOKEN="..."
+GITHUB_TOKEN=""
 
 # GitHub repo to pull docs from
 SOURCE_REPO="remix-run/remix"
@@ -15,6 +10,9 @@ RELEASE_PACKAGE="remix"
 # For development, reading the docs from a local repo
 LOCAL_REPO_RELATIVE_PATH="../remix"
 
+# Only needed locally if testing newsletter signup -- get from https://app.convertkit.com/account_settings/advanced_settings
+CONVERTKIT_KEY="..."
+
 # Not used locally, but make sure this is set in GitHub for production
 FASTLY_API_TOKEN="..."
-FASTLY_SERVICE_ID="..."
+FASTLY_SERVICE_ID="..."

README.md

@@ -1,22 +1,30 @@
 # Remix Website
 
-## Installation
+## Setup
 
 First setup your `.env` file, use `.env.example` to know what to set.
 
+```sh
+cp .env.example .env
+```
+
+Install dependencies
+
 ```sh
 npm i
 ```
 
+## Local Development
+
 Now you should be good to go:
 
 ```sh
 npm run dev
 ```
 
-To preview local changes to the `docs` folder in the Remix repo, select "local" from the version dropdown menu on the site.
+To preview local changes to the `docs` folder in the Remix repo, select "local" from the version dropdown menu on the site. Make sure you have the [remix repo](https://github.com/remix-run/remix) cloned locally and `LOCAL_REPO_RELATIVE_PATH` is pointed to the correct filepath.
 
-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.
+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
@@ -55,15 +63,7 @@ When you're happy with it, merge your branch into `main` and push.
 
 ## Content
 
-Content is synced to the SQLite distributed system from the `main` branch. You do not need to deploy a tag in order to add or update content.
-
-```sh
-git push origin main
-# watch the app instances pull the new content
-fly logs -a remixdotrun
-```
-
-**Authoring Blog Articles:**
+### Authoring Blog Articles
 
 - Put a markdown file in `data/posts/{your-post-slug}.md`
 - Follow the conventions found in other blog articles for author/meta
@@ -76,14 +76,27 @@ fly logs -a remixdotrun
 
 When linking to other posts use `[name](article-slug)`, you don't need to do `[name](/blog/article-slug)`
 
-**Changing page content:**
+### Adding to Showcase
+
+[The Showcase](https://remix.run/showcase) page is a collection of sites built on Remix that are particularly impressive. If you think there is something missing from this list, feel free to open a PR for the team to review.
+
+- Record quick demo of the website (~6s)
+- Grab or screenshot the first frame of the video
+- Add both resources to public/showcase-assets
+- Run `cd public/showcase-assets && ./convert.sh` to convert images and videos to compressed formats
+  - Warning: this script was created hastily with ChatGPT and little concern for others running it. Feel free to offer improvements to the script and/or documentation
+- Remove/don't commit the original video and image
+- Add new showcase example data to [showcase.yaml](./data/showcase.yaml)
+
+### Adding to Resources
+
+[The Resources](https://remix.run/resources) page is a collection of templates and libraries that make building sites with Remix even easier. For now this data is driven by a yaml file, but eventually we anticipate replacing it with a database.
 
-- Edit markdown files in `content/{pages,other}/{file}.md`
-- Push to `main`
+If you would like to contribute a new resource to these pages, simply add it to [resources.yaml](./data/resources.yaml)
 
 ## CSS Notes
 
-You'll want the tailwind VSCode plugin fer sure, the hints are amazing.
+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" />`.
 
@@ -95,6 +108,6 @@ We want to use Tailwind's default classes as much as possible to avoid a large C
 
 ## Algolia Search
 
-We use [DocSearch](https://docsearch.algolia.com/) by Algolia for our documetnations search. The site is automatically scraped and an index generated weekly by the [Algolia Crawler](https://crawler.algolia.com/).
+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/env.server.ts

@@ -23,8 +23,6 @@ const requiredInDevelopment: z.RefinementEffect<
 };
 
 const envSchema = z.object({
-  FLY_APP_NAME: z.string(),
-
   // Get from https://app.convertkit.com/account_settings/advanced_settings
   CONVERTKIT_KEY: z.string().optional().superRefine(requiredInProduction),
 

app/lib/github.server.ts

@@ -1,4 +1,6 @@
 import { Octokit } from "octokit";
 import { env } from "~/env.server";
 
-export const octokit = new Octokit({ auth: env.GITHUB_TOKEN });
+export const octokit = new Octokit(
+  env.GITHUB_TOKEN ? { auth: env.GITHUB_TOKEN } : undefined,
+);