[WIP] Related content links (#6360)

* WIP: get well in bottom of page

* New RelatedContent component.

* Added related content for POC

* Added more related content cards

* Updated guides index

* Styles fix for inline code within <Well> component

Co-authored-by: Thomas Walker <bladey@me.com>

docs/components/RelatedContent.tsx

@@ -0,0 +1,24 @@
+/** @jsx jsx */
+import { jsx } from '@emotion/react';
+import { ReactNode } from 'react';
+
+import { useMediaQuery } from '../lib/media';
+
+export function RelatedContent({ children }: { children: ReactNode }) {
+  const mq = useMediaQuery();
+
+  return (
+    <div
+      css={mq({
+        display: 'grid',
+        gridTemplateColumns: ['1fr', '1fr', '1fr', '1fr 1fr'],
+        gap: 'var(--space-xlarge)',
+        '> a > p > p > code': {
+          textDecoration: 'none',
+        },
+      })}
+    >
+      {children}
+    </div>
+  );
+}

docs/components/primitives/Well.tsx

@@ -27,6 +27,7 @@ export function Well({ grad = 'grad1', heading, href, children, ...props }: Well
           color: 'var(--text)',
           overflow: 'hidden',
           transition: 'box-shadow 0.2s ease, transform 0.2s ease, padding 0.2s ease',
+          textDecoration: 'none !important',
           ':before': {
             content: '""',
             position: 'absolute',
@@ -47,8 +48,9 @@ export function Well({ grad = 'grad1', heading, href, children, ...props }: Well
           as="h2"
           look="heading20bold"
           css={{
-            margin: '0 0 1rem 0',
+            margin: '0 0 1rem 0 !important',
             paddingRight: '2rem',
+            fontSize: '1.25rem !important',
           }}
         >
           {heading} →

docs/pages/docs/apis/auth.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Authentication API
 
@@ -475,4 +477,15 @@ If the token has expired the value `{ code: TOKEN_EXPIRED, message: 'The auth to
 If the token is valid then the session handler will start a new session and return the encoded session cookie data as `sessionToken`.
 The authenticated item will be returned as `item`.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Example Project: Authentication"
+    href="https://github.com/keystonejs/keystone/tree/master/examples/with-auth"
+    >
+    Adds password-based authentication to the Task Manager starter project.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="API reference for supporting authentication against a password field using the createAuth() function in the `@keystone-next/auth` package.">{children}</Markdown>;

docs/pages/docs/apis/config.mdx

@@ -1,4 +1,7 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
+import { InlineCode } from '../../../components/primitives/Code';
 
 # System Configuration API
 
@@ -404,4 +407,15 @@ Options:
 - `generateNextGraphqlAPI`: Creates a file at `node_modules/.keystone/next/graphql-api` with `default` and `config` exports that can be re-exported in a Next API route
 - `generateNodeAPI`: Creates a file at `node_modules/.keystone/api` with a `lists` export
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Schema API Reference"
+    href="/docs/apis/schema"
+    >
+    The API to configure your  options used with the <InlineCode>list</InlineCode> function.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="API reference for configuring your Keystone system: Lists, Database, Admin UI, Server, Sessions, GraphQl, Files, Images, and experimental options.">{children}</Markdown>;

docs/pages/docs/apis/context.mdx

@@ -1,4 +1,7 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
+import { InlineCode } from '../../../components/primitives/Code';
 
 # Context API
 
@@ -161,4 +164,21 @@ They will be removed in future releases.
 
 `gqlNames`: A function which takes a `listKey` and returns an object containing the GraphQL query, mutation and type names related to that list.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="List Items API Reference"
+    href="/docs/apis/list-items"
+    >
+    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.lists.&lt;listName&gt;</InlineCode>
+  </Well>
+  <Well
+    heading="DB Items API Reference"
+    href="/docs/apis/db-items"
+    >
+    The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="The KeystoneContext object is the primary API entry point for all of the run-time functionality of your system. It's APIs can be used to write things like access control, hooks, testing and GraphQL schema extensions.">{children}</Markdown>;

docs/pages/docs/apis/db-items.mdx

@@ -1,4 +1,7 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
+import { InlineCode } from '../../../components/primitives/Code';
 
 # Database Items API
 
@@ -140,4 +143,21 @@ const users = await context.db.lists.User.deleteMany({
 });
 ```
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="List Items API Reference"
+    href="/docs/apis/list-items"
+    >
+    A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.lists.&lt;listName&gt;</InlineCode>.
+  </Well>
+  <Well
+    heading="Context API Reference"
+    href="/docs/apis/context"
+    >
+    The API for run-time functionality in your Keystone system. Use it to write business logic for access control, hooks, testing, GraphQL schema extensions, and more.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Keystone’s database items API is a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system. It bypasses the GraphQL Server itself, invoking resolver functions directly.">{children}</Markdown>;

docs/pages/docs/apis/fields.mdx

@@ -1,4 +1,7 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
+import { InlineCode } from '../../../components/primitives/Code';
 
 # Fields API
 
@@ -732,4 +735,21 @@ export default config({
 });
 ```
 
-export default ({ children }) => <Markdown description="A reference of Keystone’s field types, and the configuration options they accept.">{children}</Markdown>;
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Schema API Reference"
+    href="/docs/apis/schema"
+    >
+    The API to configure your  options used with the <InlineCode>list()</InlineCode> function.
+  </Well>
+  <Well
+    heading="GraphQL API Reference"
+    href="/docs/apis/graphql"
+    >
+    A complete CRUD (create, read, update, delete) GraphQL API derived from the list and field names you configure in your system.
+  </Well>
+</RelatedContent>
+
+export default ({ children }) => <Markdown description="A reference of Keystone’s field types, and the configuration options they accept.">{children}</Markdown>

docs/pages/docs/apis/filters.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Query Filter API
 
@@ -149,4 +151,15 @@ The `file` field type does not support filters.
 
 The `image` field type does not support filters.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Query Filters Guide"
+    href="/docs/guides/filters"
+    >
+    Query filters are an integral part of Keystone’s powerful GraphQL APIs. This guide will show you how to use filters to get the data you need from your system.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="A reference list of every filters available for every Keystone field type. Keystone filters are typically named after the field they are filtering.">{children}</Markdown>;

docs/pages/docs/apis/graphql.mdx

@@ -1,4 +1,7 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
+import { InlineCode } from '../../../components/primitives/Code';
 
 # GraphQL API
 
@@ -409,4 +412,21 @@ type User {
 }
 ```
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Schema API Reference"
+    href="/docs/apis/schema"
+    >
+    The API to configure your  options used with the <InlineCode>list()</InlineCode> function.
+  </Well>
+  <Well
+    heading="Config API Reference"
+    href="/docs/apis/config"
+    >
+    The API to configure all the parts parts of your Keystone system.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Reference docs for Keystone’s CRUD (create, read, update, delete) GraphQL API. Based on the schema definitions outlined in your system config.">{children}</Markdown>;

docs/pages/docs/apis/hooks.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Hooks API
 
@@ -438,4 +440,15 @@ The data resolving steps are applied in the following order:
 5. Field hooks (user defined): A `resolveInput` field hook can return a new value for its field, which will the current field value on `resolvedData`.
 6. List hooks (user defined): A `resolveInput` list hook can return a new value for the entire `resolvedData` object.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Hooks Guide"
+    href="/docs/guides/hooks"
+    >
+    Learn how to use Hooks within your schema to extend Keystone’s powerful CRUD GraphQL APIs with your own business logic.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Hooks let you to execute code at different stages of the mutation lifecycle when performing create, update, and delete operations.">{children}</Markdown>;

docs/pages/docs/apis/list-items.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # List Items API
 
@@ -144,4 +146,21 @@ const users = await context.lists.User.deleteMany({
 });
 ```
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Context API Reference"
+    href="/docs/apis/context"
+    >
+    The API for run-time functionality in your Keystone system. Use it to write business logic for access control, hooks, testing, GraphQL schema extensions, and more.
+  </Well>
+  <Well
+    heading="DB Items API Reference"
+    href="/docs/apis/db-items"
+    >
+    The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Reference docs for Keystone‘s List Items API: a programmatic API for running CRUD operations against your GraphQL API.">{children}</Markdown>;

docs/pages/docs/apis/schema.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Schema API
 
@@ -207,4 +209,29 @@ export default config({
 The `description` option defines a string which will be used as a description in the Admin UI and GraphQL API docs.
 This option can be individually overridden by the `graphql.description` or `ui.description` options.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Fields API Reference"
+    href="/docs/apis/fields"
+    >
+    Defines the names, types, and configuration of Keystone fields. See all the fields and the configuration options they accept.
+  </Well>
+  <Well
+    heading="Config API Reference"
+    href="/docs/apis/config"
+    >
+    The API to configure all the parts parts of your Keystone system.
+  </Well>
+  <Well
+    heading="Example Project: Blog"
+    href="https://github.com/keystonejs/keystone/tree/master/examples/blog"
+    target="_blank"
+    rel="noopener noreferrer"
+    >
+    A basic Blog schema with Posts and Authors. Use this as a starting place for learning how to use Keystone. It’s also a starter for other feature projects.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Reference docs for Keystone’s Schema API, which defines the data model of your system.">{children}</Markdown>;

docs/pages/docs/apis/session.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Session API
 
@@ -122,4 +124,23 @@ If you configure your Keystone session with session management then the [`Keysto
 The `startSession` and `endSession` functions will be used by [authentication mutations](./auth) to start and end authenticated sessions.
 These mutations will set the value of `session` to include the values `{ listKey, itemId }`.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Config API Reference"
+    href="/docs/apis/config"
+    >
+    The API to configure all the parts parts of your Keystone system.
+  </Well>
+  <Well
+    heading="Example Project: Authentication"
+    href="https://github.com/keystonejs/keystone/tree/master/examples/with-auth"
+    target="_blank"
+    rel="noopener noreferrer"
+    >
+    Adds password-based authentication to the Task Manager starter project.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Reference docs for the session property of Keystone’s system configuration object.">{children}</Markdown>;

docs/pages/docs/guides/cli.mdx

@@ -1,4 +1,6 @@
 import { Markdown } from '../../../components/Markdown';
+import { Well } from '../../../components/primitives/Well';
+import { RelatedContent } from '../../../components/RelatedContent';
 
 # Command Line
 
@@ -186,4 +188,15 @@ yarn keystone-next start
 - If you promote your build through separate environments in a pipeline (e.g testing → staging → production) you should run migrations during the **promote** step and **not** as part of the build script.
 - It is important you do **not run migrations against your production database from staging builds**. If you have staging or preview environments set up in production, make sure they are not pointed to your production database.
 
+## Related resources
+
+<RelatedContent>
+  <Well
+    heading="Getting Started with create-keystone-app"
+    href="/docs/walkthroughs/getting-started-with-create-keystone-app"
+    >
+    How to use Keystone's CLI app to standup a new local project with an Admin UI & the GraphQL API playground.
+  </Well>
+</RelatedContent>
+
 export default ({ children }) => <Markdown description="Learn how to use Keystone's command line interface (CLI) to develop, build, and deploy your Keystone projects.">{children}</Markdown>;