@walltowall/gatsby-theme-ww-prismic-docs

@walltowall/gatsby-theme-slice-studio

Gatsby theme that provides interactive client documentation for Wall-to-Wall Gatsby websites.

Install

yarn add @walltowall/gatsby-theme-ww-slice-studio

How to use

Configure Gatsby

Setup the consuming project's gatsby-config as shown below:

// In your gatsby-config.js
plugins: [
  {
    resolve: '@walltowall/gatsby-theme-ww-slice-studio',
    options: {
      // Path to the project's root directory. This is required and should be set to __dirname.
      root: __dirname,

      // Name of the client for the site. Will appear throughout documentation.
      siteTitle: 'Site Title',

      // Provide an object of Prismic custom type JSON schemas to load into Gatsby.
      schemas,

      // Provide a list of layouts to show in the client documentation. Each named layout should have a corresponding
      // .js file in `/studio/layouts`.
      layouts: [
        'about',
        'design',
        'home',
        'project',
        'services',
        'recognition',
        'team',
      ],

      // Provide an object of Prismic custom types and slice zones. These keys should have corresponding entries
      // from the provided `schemas` object.
      sliceZones: {
        page: {
          description:
            'Each page document in Prismic represents a unique and visitable page on your website.',
          zones: {
            body:
              "Body slices comprise the majority of the content on it's respective page.",
          },
        },
      },
    },
  },
]

Configure Netlify & Authentication

Once your gatsby-config has been set-up, you'll need to configure a netlify.toml in your project root to serve the appropriate lambda functions for authentication. Below is the absolute minimum you'll need to configure lambda functionality.

[build]
  functions = "node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda"

After setting up your .toml file, ensure to add the appropriate environment variables to your Netlify site's dashboard. See .env for the values to enter.

Writing documentation

Layouts

As shown in the example gatsby-config, every defined layout will need to have a corresponding .js file in your project's /studio/layouts that follow the following structure:

export const LAYOUT_NAME = {
  // The display name for this layout.
  name: 'Name',

  // The custom type in Prismic this layout is available under.
  customType: 'page',

  // A short description for this layout.
  description: 'Sample description',

  // The list of slices to pre-populate the Prototyper when this layout is selected.
  // Must be a list of tuples containing the full slice name and the example index to render.
  example: [
    ['PageBodyHorizontalNavigation', 0],
    ['PageBodyFeaturedProjects', 0],
    ['PageBodyMixedSizedProjects', 0],
  ],

  // A list of zones to render in the layout documentation.
  // A zone can render any arbitrary JSX and label itself with a name and
  // reasoning.
  zones: [
    {
      // If you would like to render JSX without displaying any additional info,
      // e.g. rendering a <Header /> or <Footer />, just omit the `name`, property.
      render: () => <PageBodyHeader nextSharesBg={[true]} />,
    },
    {
      // Heading for the zone.
      name: 'Navigation',

      // If a zone is from a "preset", designate it as one with the `preset` property.
      // This will prevent this zone from being modified in the Prototyper tool.
      preset: 'Horizontal Navigation',

      // Client friendly reasoning as to why these slices were selected.
      reasoning:
        'Provides quick access to different project types for visitors.',

      // The actual JSX to render for this zone.
      render: () => (
        <PageBodyHorizontalNavigation
          title="design"
          rootHref="/"
          nextSharesBg={[true]}
        >
          <PageBodyHorizontalNavigation.Item href="/">
            Hospitality + Leisure
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Interior Design
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Office + Healthcare
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Residential
          </PageBodyHorizontalNavigation.Item>
          <PageBodyHorizontalNavigation.Item href="/">
            Retail + Restaurants
          </PageBodyHorizontalNavigation.Item>
        </PageBodyHorizontalNavigation>
      ),
    },
    {
      name: 'Project Grid',

      // If a zone is not a preset, include the exact list of slices used in the example.
      slices: ['PageBodyFeaturedProjects', 'PageBodyBrandedCallout'],

      // In addition to the exact list, also provide a list of recommended slices for this zone.
      // In some designs, this may differ from `slices` since an example may not include every slice
      // that would be appropriate.
      recommendedSlices: [
        'PageBodyFeaturedProjects',
        'PageBodyMixedSizedProjects',
        'PageBodySmallProjects',
        'PageBodyBrandedCallout',
      ],
      reasoning:
        'Varied usage of the recommended slices helps give the layout a dynamic flow. The callout helps to provide a break in the list of projects.',
      render: () => (
        <>
          <PageBodyFeaturedProjects nextSharesBg={[true]}>
            <PageBodyFeaturedProjects.Project
              variant="large"
              imageURL="https://pvadev.cdn.prismic.io/pvadev/541704ba04a3f58caa4a37dd325d793d351dbd1d_0-flower-avenue.jpg"
              imageAlt="Example."
              location="Honolulu, Hawaii"
              categoryUID="residential"
              name="Flower Avenue"
              href={true}
            />
          </PageBodyFeaturedProjects>
          <PageBodyBrandedCallout
            variant="dark"
            textHTML="<h1>Our team of architects and interior designers is both collaborative and visionary.</h1>"
            buttonHref={true}
            buttonText="Our approach"
            nextSharesBg={[true]}
          />
          <PageBodyFooter />
        </>
      ),
    },
  ],
}

Once you have written all of your required layouts, create /studio/layouts/index.js in your project and export all of your layouts as named exports:

export { project } from './project'
export { otherLayout } from './otherLayout'

Slices

To write documentation for individual slices, create a docs object property on the slice component directly.

See below for an example:

export const PageBodyText = props => {
  // ... implementation details
}

// At the end of the file, add the `docs` object to the component.
PageBodyText.docs = {
  // The display name of the slice.
  name: 'Text',

  // List of examples of this slice. If a slice has variations of itself, each variant should be included.
  examples: [
    {
      // Name of the example. This will show in the prototyper tool.
      name: 'With Heading',

      // Corresponding JSX for this example.
      render: () => <PageBodyText />,
    },
  ],
}

General Documentation

To write additional general documentation, you can create additional markdown files in the /src/docs directory of this theme.

Each markdown file should have generally follow the following frontmatter:

---
parent: General
title: Images
path: general/images
summary: >-
  Short summary of article
---

List of Required Files

Due to the nature of aliased imports with webpack, below is a comprehensive list of required files that your project needs for this theme to function correctly:

• src/index.css: Your fonts and base styles to inject into each Studio Frame.
• src/slices/index.js: Export slicesMap as PageBody from
• src/slices/PageBody: so our theme has alias access to it.
• /netlify.toml: Must be configured to point to the theme's lambda folder. Ex: node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda
• studio/layouts: Must contain your layouts and the appropriate index.js