@walltowall/gatsby-source-prismic-docs
v0.1.1
Published
Gatsby source plugin for building documentation for sites using Prismic as a data source
Downloads
6
Readme
@walltowall/gatsby-source-prismic-docs
Gatsby source plugin for Prismic slice documentation.
Gatsby source plugin for building documentation for sites using Prismic as a data source.
Table of Contents
Features
TODO
Install
npm install --save @walltowall/gatsby-source-prismic-docs
How to use
// In your gatsby-config.js
plugins: [
/**
* Gatsby's data processing layer begins with "source" plugins. Here the site
* sources its data from your documentation files.
*/
{
resolve: '@walltowall/gatsby-source-prismic-docs',
options: {
/**
* Provide an array of SliceDocumentation objects.
*/
sliceDocumentations: [SliceDocumentation(/* ... */)],
/**
* Provide an array of CustomTypeDocumentation objects.
*/
customTypeDocumentations: [CustomTypeDocumentation(/* ... */)],
/**
* Provide an array of LayoutDocumentation objects.
*/
layoutDocumentations: [LayoutDocumentation(/* ... */)],
/**
* Provide an array of GuideGroup objects.
*/
guideGroups: [GuideGroup(/* ... */)],
},
},
]
Documenting Slices
Slices are documented using the SliceDocumentation
struct.
The markdown
helper can be used when lengthier content is needed, such as the
about
field.
const {
SliceDocumentation,
SliceExample,
textField,
lorem,
markdown,
} = require('@walltowall/gatsby-source-prismic-docs')
module.exports = SliceDocumentation({
qualifiedName: 'PageBodyText',
about: markdown`
About the slice
`,
relatedSlices: ['PageBodyImages'],
examples: [
SliceExample({
name: 'Example name',
data: ({
heading = lorem('2w'),
paragraphs = [lorem('40w'), lorem('30w'), lorem('50w')],
}) => ({
primary: {
heading: textField(heading),
text: textField(paragraphs.map(x => `<p>${x}</p>`).join('')),
},
}),
}),
],
})
Providing examples
Slice examples are created using the SliceExample
struct. These structs create
mock data from Prismic in the shape the Slice expects.
The data
field should be a function that returns mock Prismic data for the
slice. The content of the examples can be configured using the function's first
argument like the example above. These overrides may be useful when creating
layout documentation.
The meta
field should be a function that returns mock data for the meta
object used in mapDataToProps
and mapDataToContext
in
MapSlicesToComponents
. Like the data
field, the content of the example meta
object can be configured using the function's first argument. These overrides
may be useful when creating layout documentation.
Helpers are available to mock Prismic fields quickly.
textField
: Creates a Structured Text field (i.e. Rich Text, Title).linkField
: Creates a link field. Usually used with no arguments to create a stub link.imageFieldFluid
: Creates an Image field withgatsby-source-prismic
's Gatsby Image fluid builder.lorem
: Returns placeholder "Lorem ipsum" text.
Documenting Layouts
Layouts are documented using the LayoutDocumentation
struct.
The markdown
helper can be used when lengthier content is needed, such as the
about
field.
const {
LayoutDocumentation,
SliceExampleRef,
SliceExampleGroup,
markdown,
} = require('@walltowall/gatsby-source-prismic-docs')
module.exports = LayoutDocumentation({
customType: 'page',
name: 'Home',
description: 'Short description',
about: markdown`
About the layout.
`,
slicesMiddleware: (list = []) => [
{ __typename: 'PageBodyHeader' },
...list,
{ __typename: 'PageBodyFooter' },
],
exampleGroups: [
SliceExampleGroup({
name: 'First section of the layout',
description: markdown`
Description of the section.
`,
recommendedSlices: ['PageBodyText'],
examples: [
SliceExampleRef({
qualifiedName: 'PageBodyText',
exampleName: 'With heading',
args: {
heading: 'My cool page',
},
}),
],
}),
SliceExampleGroup({
name: 'Second section of the layout',
description: markdown`
Description of the section.
`,
recommendedSlices: ['PageBodyCallToAction'],
examples: [
SliceExampleRef({
qualifiedName: 'PageBodyCallToAction',
exampleName: 'With external link',
}),
],
}),
],
})
Providing example groups
Slice examples are combined to create an example layout using the
SliceExampleGroup
and SliceExampleRef
structs.
The SliceExampleGroup
struct groups one or more Slice examples and provides a
description of their purpose.
The SliceExampleRef
struct references an example from a given Slice using the
Slice's qualified name and the example's full name. Arguments can be passed via
the args
and metaArgs
fields to customize the mock data for the example.
If the layout requires MapSlicesToComponents
list middleware, such as adding
site-wide header and footer Slices, a middleware function can be provided to the
slicesMiddleware
field.
Documenting Custom Types
Custom types are documented using the CustomTypeDocumentation
struct.
The markdown
helper can be used when lengthier content is needed, such as the
about
field.
const {
CustomTypeDocumentation,
markdown,
} = require('@walltowall/gatsby-source-prismic-docs')
module.exports = CustomTypeDocumentation({
apiId: 'page',
description: 'Short description',
about: markdown`
About the custom type.
`,
tabDescriptions: {
main: 'Information about the page.',
body: 'Content for the page.',
},
sliceZoneDescriptions: {
main: 'Set metadata for the page.',
body: "Build the page's content using Slices.",
},
})
Documenting Guide Groups
Custom types are documented using the CustomTypeDocumentation
struct.
const { GuidesGroup } = require('@walltowall/gatsby-source-prismic-docs')
module.exports = GuidesGroup({
name: 'General',
files: [
path.join(__dirname, 'editing-content.md'),
path.join(__dirname, 'publishing.md'),
],
})
How to query
You can query nodes created from your documentation files using GraphQL like the following:
Note: Learn to use the GraphQL tool and Ctrl+Spacebar at http://localhost:8000/___graphql to discover the types and properties of your GraphQL model.
{
allPrismicDocsSlice {
nodes {
id
qualifiedName
}
}
}
All documentation schemas are pulled from your plugin options and created as
prismicDocs${nodeType}
and allPrismicDocs${nodeType}
, where ${nodeType}
is
one of the following:
Slice
SliceExample
SliceExampleGroup
ExampleData
Layout
CustomType
GuidesGroup
For example, if you want to get documentation for all custom types, you will be able to query for them like the following:
{
allPrismicDocsCustomType {
nodes {
id
displayName
}
}
}
Query Slice documentation
Query Layout documentation
Query Examples
Query Custom Type documentation
Query Guide Groups
Site's gatsby-node.js
example
const path = require('path')
exports.createPages = async ({ graphql, actions }) => {
const { createPage } = actions
const sliceDocs = await graphql(`
{
allPrismicDocsSlice {
nodes {
id
schema {
name
}
}
}
}
`)
sliceDocs.data.allPrismicDocsSlice.nodes.forEach(node => {
createPage({
path: `/slices/${node.schema.name}`,
component: path.resolve(__dirname, 'src/templates/slice.js'),
context: {
id: node.id,
},
})
})
}