Update README

README.md

@@ -1,78 +1,8 @@
-# Gatsby Theme: Iterative
+# Gatsby Theme: Iterative development monorepo
 
-This Gatsby Theme houses the shared website code for all websites for
-[Iterative](https://iterative.ai). This package is currently purpose-built
-specifically for our websites and not very useful outside of them, but we intend
-to change that as we make improvements and iron out issues!
+This repo is dedicated to the development of `gatsby-theme-iterative`, a shared
+code bundle used between all the Gatsby websites hosted by
+[Iterative, inc](iterative.ai)!
 
-## Usage
-
-### Options
-
-- disable: boolean Default: Boolean(process.env.SKIP_DOCS)
-
-- getTemplate: function Default: () => defaultGetTemplate
-
-- defaultTemplate: string Default: require.resolve('./src/templates/doc.tsx')
-
-- remark: boolean Default: true
-
-- filesystem: boolean Default: true
-
-- glossaryDirectory: string Default: 'docs/user-guide/basic-concepts'
-
-- simpleLinkerTerms: { matches: string, url: string }[] These terms will be
-  passed to the simpleLinker remark plugin
-
-- cssBase: string Used as base files for global PostCSS variables and queries
-
-- customMediaConfig: object config passed to `postcss-custom-media`
-
-- customPropertiesConfig: object config passed to `postcss-custom-properties`
-
-- colorModConfig: object config passed to `postcss-color-mod`
-
-- postCssPlugins: Plugin[] If specified, this array will completely replace
-  plugins this theme passes to PostCSS. This is mostly an escape hatch for if
-  styles are broken with the default plugins. Check out
-  [the theme's `gatsby-config`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/gatsby-theme-iterative/gatsby-config.js)
-  to see the default plugins, as not having them in this option will very likely
-  break core functionality.
-
-### Examples
-
-See this example from
-[the example website's `gatsby-config.js`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/example/gatsby-config.js).
-
-```js
-const path = require('path')
-const {
-  name: themePackageName
-} = require('../gatsby-theme-iterative/package.json')
-
-module.exports = {
-  trailingSlash: 'never',
-  siteMetadata: {
-    title: 'Example website',
-    description: 'Example website description',
-    keywords: ['docs', 'test'],
-    siteUrl: 'http://localhost:8000'
-  },
-  plugins: [
-    {
-      resolve: themePackageName,
-      options: {
-        simpleLinkerTerms: require('./content/linked-terms')
-      }
-    },
-    {
-      resolve: 'gatsby-source-filesystem',
-      options: {
-        name: 'images',
-        path: path.join(__dirname, 'static', 'img')
-      }
-    },
-    '@sentry/gatsby'
-  ]
-}
-```
+For more details about the theme itself, check out its
+[README](packages/gatsby-theme-iterative/README.md)!

packages/gatsby-theme-iterative/README.md

@@ -0,0 +1,156 @@
+# Gatsby Theme: Iterative
+
+This Gatsby theme is what [Iterative, inc.](https://iterative.ai) uses to power
+all of our Gatsby websites! It contains all of our shared utility code, as well
+as our full docs engine. This project is still evolving, and while it's
+currently very specific to iterative.ai websites we hope to make it usable for
+others in the future.
+
+## Usage
+
+### Options
+
+- disable: boolean
+
+  Default: Boolean(process.env.SKIP_DOCS)
+
+  Stops this theme from making pages. Could be used as a conditional for test
+  and development purposes.
+
+- defaultTemplate: string
+
+  Default: require.resolve('./src/templates/doc.tsx')
+
+  Will be passed to the `getTemplate` function to use as a default template, the
+  default function simply returns this if `template` isn't specified.
+
+- getTemplate: function
+
+  Default:
+
+  ```ts
+  const defaultGetTemplate = (template, defaultTemplate) =>
+    template
+      ? require.resolve(path.resolve('src', 'templates', template + '.tsx'))
+      : defaultTemplate
+  ```
+
+  This function will be given the `template` field specified in the page's
+  frontmatter, as well as the `defaultTemplate` specified by the option above.
+  It is expected to return the absolute path to a React component to be given to
+  Gatsby's `createPage` action.
+
+- remark: boolean
+
+  Default: true
+
+  if true, this theme will add its own instance of `gatsby-transformer-remark`.
+
+- filesystem: boolean
+
+  Default: true
+
+  if true, this theme will add its own instance of `gatsby-source-filesystem`.
+
+- glossaryPath: string
+
+  Default: path.resolve('content', 'docs', 'user-guide', 'basic-concepts')
+
+- simpleLinkerTerms: { matches: string, url: string }[]
+
+  Default: undefined
+
+  These terms will be passed to `plugins/gatsby-remark-dvc-linker`, which will
+  scan code blocks for ones with content matching `matches`, and then link it to
+  that entry's `url`.
+
+- postCssPlugins: Plugin[]
+
+  Default:
+
+  ```js
+  const postCssPlugins = [
+    require('tailwindcss/nesting')(require('postcss-nested')),
+    autoprefixer,
+    require('tailwindcss')
+  ]
+  ```
+
+  If specified, this array will completely replace plugins this theme passes to
+  PostCSS. This is mostly an escape hatch for if styles are broken with the
+  default plugins. Check out
+  [the theme's `gatsby-config`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/gatsby-theme-iterative/gatsby-config.js)
+  to see the default plugins, as not having them in this option will very likely
+  break core functionality.
+
+- docsInstanceName: string
+
+  Default: 'iterative-docs'
+
+  The `name` that will be passed to the `gatsby-source-filesystem` instance for
+  docs pages. The resulting `sourceInstanceName` will be used to identify files
+  that will be processed as docs pages.
+
+- docsPath: string
+
+  Default: path.resolve('content', 'docs')
+
+- glossaryInstanceName: string
+
+  Default: 'iterative-glossary'
+
+  The `name` that will be passed to the `gatsby-source-filesystem` instance for
+  glossary entries. The resulting `sourceInstanceName` will be used to identify
+  files that will be processed as glossary pages.
+
+- argsLinkerPath: string
+
+  Default: ['command-reference', `ref`, 'cli-reference']
+
+  The path that `plugins/gatsby-remark-args-linker` will operate on, connecting
+  arguments listed in the summary with their summaries deeper in the page.
+
+- docsPrefix: string
+
+  Default: 'doc'
+
+  This is the prefix that the docs pages will render to, including the index
+  page at the exact path.
+
+### Examples
+
+See this example from
+[the example website's `gatsby-config.js`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/example/gatsby-config.js).
+
+```js
+const path = require('path')
+const {
+  name: themePackageName
+} = require('../gatsby-theme-iterative/package.json')
+
+module.exports = {
+  trailingSlash: 'never',
+  siteMetadata: {
+    title: 'Example website',
+    description: 'Example website description',
+    keywords: ['docs', 'test'],
+    siteUrl: 'http://localhost:8000'
+  },
+  plugins: [
+    {
+      resolve: themePackageName,
+      options: {
+        simpleLinkerTerms: require('./content/linked-terms')
+      }
+    },
+    {
+      resolve: 'gatsby-source-filesystem',
+      options: {
+        name: 'images',
+        path: path.join(__dirname, 'static', 'img')
+      }
+    },
+    '@sentry/gatsby'
+  ]
+}
+```

packages/gatsby-theme-iterative/config-defaults.js

@@ -1,8 +1,9 @@
 const path = require('path')
+
 module.exports = {
-  glossaryPath: path.resolve('content', 'docs', 'user-guide', 'basic-concepts'),
   docsPath: path.resolve('content', 'docs'),
-  glossaryInstanceName: 'iterative-glossary',
   docsInstanceName: 'iterative-docs',
+  glossaryPath: path.resolve('content', 'docs', 'user-guide', 'basic-concepts'),
+  glossaryInstanceName: 'iterative-glossary',
   argsLinkerPath: ['command-reference', `ref`, 'cli-reference']
 }

packages/gatsby-theme-iterative/gatsby-node.js

@@ -16,7 +16,7 @@ exports.pluginOptionsSchema = ({ Joi }) => {
     ),
     remark: Joi.boolean().default(true),
     filesystem: Joi.boolean().default(true),
-    glossaryDirectory: Joi.string().default(
+    glossaryPath: Joi.string().default(
       path.resolve('content', 'docs', 'user-guide', 'basic-concepts')
     ),
     docsDirectory: Joi.string().default(path.resolve('content', 'docs')),
@@ -29,8 +29,6 @@ exports.pluginOptionsSchema = ({ Joi }) => {
         url: Joi.string()
       })
     ),
-    cssBase: Joi.string(),
-    customMediaConfig: Joi.object(),
     postCssPlugins: Joi.array(),
     argsLinkerPath: Joi.alternatives()
       .try(Joi.string(), Joi.array().items(Joi.string()))