Scaffold the site

Created by: shawnbot

This scaffolds out the Next setup and some pages to test the navigation. Here's the lowdown:

1. We have a private package.json now that offers the following run-scripts for local development:

   • npm run dev starts up the Next dev server at http://localhost:3000

   • npm run lint lints all the JS files in src/ and pages/ using (basically) the same eslint config as Primer Components

2. All of the pages live in the pages/ directory. I've tried to stub out directories in such a way that they make sense given the nav layout, but it will probably need another pass once we've set up path aliases on primer.style. The layout looks like this:

   pages
   ├── _app.js
   ├── _document.js
   ├── design
   │   ├── communication
   │   ├── foundation
   │   │   ├── color.mdx
   │   │   └── index.mdx
   │   ├── global
   │   │   ├── accessibility.mdx
   │   │   └── index.mdx
   │   └── index.mdx
   ├── index.mdx
   └── tools
       └── index.mdx

   See .github/contributing.md for basic content contribution docs.

3. Navigation is built from a mapping of the URLs and the presence or absence of metadata in the MDX files, specifically:

   • The top nav is built from any page that exports const meta = {nav: 'top'}. Highlighting is controlled by whichever link's path matches the beginning of the current URL and is more specific (e.g. /design/tools matches /design/tools/figma more "specifically" than /design).

   • The side nav is built from the following logic:

     • If the current page exports const meta = {nav: 'side'}, then we list all of its parent's links that do so.
     • Otherwise, we work our way up the "tree" of the page hierarchy from the current page's parent and stop if we find one with children that have const meta = {nav: 'side'}.

     I know, it's confusing! This was the only way that I could figure out getting it to "work" the way we've specced it and not having to hard-code anything in the nav. If this gets difficult to work with, we can always go back to doing that.

4. We have an Actions workflow that installs and lints the repo then deploys to Now and aliases the most recent deployment to primer-design-{branch}.now.sh. You can see the preview for this branch at primer-design-site.now.sh. When this all goes well, a deployed commit's statuses will include not one, not two, but three items for deployment:

   

   In a nutshell: deploy comes from the "stock" Now deployment action that creates a randomly-named deployment, e.g. primer-design-abcd1234.now.sh; deploy/alias comes from the action that does the aliasing to primer-design-{branch}.now.sh; and deploy/preview is a commit status created to link directly to the preview URL, since any statuses with the deploy/alias context are blown away when the action finishes.

   The "Details" link for deploy/preview will always take you right to the preview URL — no ugly Zeit interstitial page! 🎉

TODO?

• Make it possible to "hide" pages (at least in the nav) with export const meta = {hidden: true}
• Fix FOUC (😱)