Merge pull request #2 from primer/rezrah/add-getting-started-page

Add getting started page

.changeset/small-chefs-work.md

@@ -0,0 +1,5 @@
+---
+'@primer/doctocat-nextjs': patch
+---
+
+Remove code blocks stylesheet, now merged into global.css

.github/workflows/deploy.yml

@@ -1,8 +1,4 @@
-# Sample workflow for building and deploying a Next.js site to GitHub Pages
-#
-# To get started with Next.js see: https://nextjs.org/docs/getting-started
-#
-name: Deploy Next.js site to Pages
+name: Deploy to production
 
 on:
   # Runs on pushes targeting the default branch
@@ -12,6 +8,9 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+env:
+  IS_PROD: true
+
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
@@ -59,16 +58,6 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v3
 
-      - name: Restore cache
-        uses: actions/cache@v3
-        with:
-          path: |
-            .next/cache
-          # Generate a new cache whenever packages or source files change.
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
-          # If source files changed but packages didn't, rebuild from a prior cache.
-          restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
       - name: Install dependencies
         run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
 

.github/workflows/deploy_preview.yml

@@ -0,0 +1,26 @@
+name: Deploy preview
+
+on:
+  pull_request:
+
+env:
+  IS_PROD: false
+
+permissions:
+  checks: write
+  contents: read
+  deployments: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    if: ${{ github.repository == 'primer/doctocat-nextjs' }}
+    name: Preview
+    # SHA for security hardening. Points at last verified HEAD of main branch.
+    uses: primer/.github/.github/workflows/deploy_preview.yml@0cec9b9914f358846163f2428663b58da41028c9
+    with:
+      node_version: 18
+      install: npm ci
+      build: npm run build
+      output_dir: packages/site/out

packages/site/.prettierrc.js

@@ -1,3 +1,7 @@
 module.exports = {
   ...require('@github/prettier-config'),
+  trailingComma: 'all',
+  bracketSpacing: false,
+  semi: false,
+  singleQuote: true,
 }

packages/site/next.config.js

@@ -3,7 +3,7 @@ const withDoctocat = require('@primer/doctocat-nextjs/doctocat.config')
 module.exports = {
   ...withDoctocat({
     output: 'export',
-    basePath: process.env.GITHUB_ACTIONS === 'true' ? '/doctocat-nextjs' : '',
+    basePath: process.env.GITHUB_ACTIONS === 'true' && process.env.IS_PROD ? '/doctocat-nextjs' : '',
     publicRuntimeConfig: {
       siteTitle: 'Doctocat',
       repo: 'https://github.com/primer/doctocat-nextjs',

packages/site/pages/_app.tsx

@@ -1,7 +1,6 @@
 // eslint-disable-next-line filenames/match-regex
 import {AppProps} from 'next/app'
 import '@primer/doctocat-nextjs/css/global.css'
-import '@primer/doctocat-nextjs/css/code-block-overrides.css'
 
 function CustomApp({Component, pageProps}: AppProps) {
   return <Component {...pageProps} />

packages/site/pages/getting-started/index.mdx

@@ -0,0 +1,5 @@
+---
+title: Getting started
+description: Learn how to create a new site with Doctocat
+menu-position: 1
+---

packages/site/pages/getting-started/introduction.mdx

@@ -0,0 +1,83 @@
+---
+title: Introduction
+description: Learn how to create a new site with Doctocat
+---
+
+This guide will walk you through creating, customizing, and deploying a new documentation site powered by Doctocat on [Next.js](https://nextjs.org/).
+
+## 1. Create a new Next.js installation
+
+Start by creating a new Next.js project using the [Next.js CLI](https://nextjs.org/docs/getting-started/installation):
+
+## 2. Install Doctocat (Next.js)
+
+Next, install Doctocat and its dependencies:
+
+```bash
+npm install --save @primer/doctocat-nextjs
+```
+
+## 3. Update your Next.js configuration
+
+Update your next.config.js file to use the Doctocat theme:
+
+```js
+// next.config.js
+const withDoctocat = require('@primer/doctocat-nextjs')
+
+module.exports = withDoctocat({
+  // your next.js config
+})
+```
+
+### Optional: GitHub Pages configuration
+
+If you plan to deploy your site to GitHub Pages, you'll need to add the following to your `next.config.js` file:
+
+```js
+output: 'export'
+```
+
+## 4. Add the Doctocat stylesheets
+
+Add the required Doctocat stylesheets to your `pages/_app.(tsx|jsx)` file:
+
+```js
+import { AppProps } from "next/app";
+import "@primer/doctocat-nextjs/css/global.css";
+
+function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+
+export default App;
+```
+
+## 5. Add your content
+
+Next, go ahead and put your Markdown documents (`.md` or `.mdx`) in `pages/`. Documents in `pages/` automatically become pages with URLs based on their path relative to `pages/`. For example, if you create a `pages/components/box.md` file, Doctocat will use that file to create a `/components/box` page.
+
+Important:
+
+- You must use `.md` or `.mdx` extensions for your documents.
+- Folders must contain an index.md or index.mdx file for breadcrumbs to work correctly. The contents of this file can be left empty
+
+## 6. Update Frontmatter on all pages
+
+Side navigation for your site is generated automatically from the frontmatter of your pages. To add a page to the side navigation, you must add a `title` and `description` to the frontmatter of your page. For example:
+
+```md
+---
+title: My page title
+description: My page description
+---
+```
+
+## 7. Deploy to GitHub Pages
+
+After you've customized the content of your site, you're ready to deploy. There are many ways to deploy your site, but we currently use [GitHub Pages](https://pages.github.com/) for most of our sites, and have found it to be an easy way to get sites up and running quickly.
+
+<br />
+<br />
+
+Congrats! You've shipped your first Doctocat site on Next.js 🎉

packages/site/pages/index.mdx

@@ -21,24 +21,25 @@ import Link from 'next/link'
     <Hero.Heading style={{marginTop: '-80px'}}>Doctocat</Hero.Heading>
     <Hero.Description>A Next.js theme for building Primer documentation sites</Hero.Description>
     <Box marginBlockStart={24}>
-      <Link legacyBehavior href="/content-examples/kitchen-sink">
-        <Hero.PrimaryAction href="/content-examples/kitchen-sink">Get started</Hero.PrimaryAction>
+      <Link legacyBehavior href="/getting-started/introduction">
+        <Hero.PrimaryAction href="/getting-started/introduction">Get started</Hero.PrimaryAction>
       </Link>
     </Box>
   </Hero>
 </div>
 <section style={{['--brand-Card-maxWidth']: '100%',maxWidth: '800px',margin: '0 auto', ['--brand-Grid-spacing-row']: 'var(--brand-Grid-spacing-column-gap)'}}>
   <Grid>
     <Grid.Column span={12}>
-      <Card href="#" hasBorder style={{width: '100%'}}>
-        <Card.Label color="green">New </Card.Label>
-        <Card.Image
-          src="https://via.placeholder.com/1000x200/d3d9df/d3d9df.png"
-          alt="placeholder, blank area with an gray background color"
-        />
-        <Card.Heading size="5">A big box announcing something</Card.Heading>
-        <Card.Description>Description of the thing, hopefully super enticing</Card.Description>
-      </Card>
+      <Link legacyBehavior href="/getting-started/introduction">
+        <Card href="#" hasBorder style={{width: '100%'}}>
+          <Card.Image
+            src="https://assetgeneratorstorage.blob.core.windows.net/user-generated-dev/product-landscape/84aa222c-3857-4e6c-bf6b-0b759ebf4122-1200x630-inline.png"
+            alt="placeholder, blank area with an gray background color"
+          />
+          <Card.Heading size="5">Get started</Card.Heading>
+          <Card.Description>Doctocat makes it easy to set up a documentation site so that you can focus on what's important: writing docs.</Card.Description>
+        </Card>
+      </Link>
     </Grid.Column>
     <Grid.Column span={12}>
       <Card href="#" hasBorder style={{width: '100%'}}>