From d43538193f1fd9ee71d417641ffdf5de71484262 Mon Sep 17 00:00:00 2001 From: rogermparent Date: Wed, 9 Nov 2022 11:48:22 -0500 Subject: [PATCH 1/6] Remove unused options from README and plugin options schema --- README.md | 8 -------- packages/gatsby-theme-iterative/gatsby-node.js | 2 -- 2 files changed, 10 deletions(-) diff --git a/README.md b/README.md index 57f95697..aec5a521 100644 --- a/README.md +++ b/README.md @@ -24,14 +24,6 @@ to change that as we make improvements and iron out issues! - 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 diff --git a/packages/gatsby-theme-iterative/gatsby-node.js b/packages/gatsby-theme-iterative/gatsby-node.js index 97599e58..c97aa22b 100644 --- a/packages/gatsby-theme-iterative/gatsby-node.js +++ b/packages/gatsby-theme-iterative/gatsby-node.js @@ -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())) From 21afbbd4c3d1d718682b901bf06d6dfe73b7110f Mon Sep 17 00:00:00 2001 From: rogermparent Date: Thu, 10 Nov 2022 12:40:45 -0500 Subject: [PATCH 2/6] Add new options to the README and actually indent the default options --- README.md | 80 +++++++++++++++++-- .../gatsby-theme-iterative/config-defaults.js | 5 +- .../gatsby-theme-iterative/gatsby-node.js | 2 +- 3 files changed, 77 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index aec5a521..40466eee 100644 --- a/README.md +++ b/README.md @@ -9,20 +9,52 @@ to change that as we make improvements and iron out issues! ### Options -- disable: boolean Default: Boolean(process.env.SKIP_DOCS) +- disable: boolean -- getTemplate: function Default: () => defaultGetTemplate + 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') + Default: Boolean(process.env.SKIP_DOCS) -- remark: boolean Default: true +- defaultTemplate: string -- filesystem: boolean Default: true + Will be passed to the `getTemplate` function to use as a default template, the + default function simply uses it if `template` isn't specified. -- glossaryDirectory: string Default: 'docs/user-guide/basic-concepts' + Default: require.resolve('./src/templates/doc.tsx') + +- getTemplate: function + + This function will be used to + + Default: + + ```ts + const defaultGetTemplate = (template, defaultTemplate) => + template + ? require.resolve(path.resolve('src', 'templates', template + '.tsx')) + : defaultTemplate + ``` + +- remark: boolean + + if true, this theme will add its own instance of `gatsby-transformer-remark`. + + Default: true + +- filesystem: boolean + + if true, this theme will add its own instance of `gatsby-source-filesystem`. + + Default: true + +- glossaryPath: string + + Default: path.resolve('content', 'docs', 'user-guide', 'basic-concepts') - simpleLinkerTerms: { matches: string, url: string }[] These terms will be - passed to the simpleLinker remark plugin + 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[] If specified, this array will completely replace plugins this theme passes to PostCSS. This is mostly an escape hatch for if @@ -31,6 +63,40 @@ to change that as we make improvements and iron out issues! 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 + + 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. + + Default: 'iterative-glossary' + +- argsLinkerPath: string + + The path that `plugins/gatsby-remark-args-linker` will operate on, connecting + arguments listed in the summary with their summaries deeper in the page. + + Default: ['command-reference', `ref`, 'cli-reference'] + +- docsPrefix: string + + This is the prefix that the docs pages will render to, including the index + page at the exact path. + + Default: 'doc' + ### Examples See this example from diff --git a/packages/gatsby-theme-iterative/config-defaults.js b/packages/gatsby-theme-iterative/config-defaults.js index 07a739e9..c726aad0 100644 --- a/packages/gatsby-theme-iterative/config-defaults.js +++ b/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'] } diff --git a/packages/gatsby-theme-iterative/gatsby-node.js b/packages/gatsby-theme-iterative/gatsby-node.js index c97aa22b..b933c91e 100644 --- a/packages/gatsby-theme-iterative/gatsby-node.js +++ b/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')), From 9825654fcbcaeeec9705cefaa027e290061fdd68 Mon Sep 17 00:00:00 2001 From: rogermparent Date: Thu, 10 Nov 2022 12:50:21 -0500 Subject: [PATCH 3/6] Fix formatting and make Default always on top --- README.md | 60 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 40466eee..4af1694a 100644 --- a/README.md +++ b/README.md @@ -11,22 +11,20 @@ to change that as we make improvements and iron out issues! - 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. - Default: Boolean(process.env.SKIP_DOCS) - - 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 uses it if `template` isn't specified. - Default: require.resolve('./src/templates/doc.tsx') - - getTemplate: function - This function will be used to - Default: ```ts @@ -36,29 +34,47 @@ to change that as we make improvements and iron out issues! : defaultTemplate ``` -- remark: boolean + This function will be used to - if true, this theme will add its own instance of `gatsby-transformer-remark`. +- remark: boolean Default: true -- filesystem: boolean + if true, this theme will add its own instance of `gatsby-transformer-remark`. - if true, this theme will add its own instance of `gatsby-source-filesystem`. +- 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 }[] 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`. +- simpleLinkerTerms: { matches: string, url: string }[] -- 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 + 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 + ;[ + 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. @@ -77,26 +93,26 @@ to change that as we make improvements and iron out issues! - 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. - Default: 'iterative-glossary' - - 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. - Default: ['command-reference', `ref`, 'cli-reference'] - - docsPrefix: string + Default: 'doc' + This is the prefix that the docs pages will render to, including the index page at the exact path. - Default: 'doc' - ### Examples See this example from From f317afb8af1c0bb3b7f83125d59b87833db7bc70 Mon Sep 17 00:00:00 2001 From: rogermparent Date: Fri, 11 Nov 2022 14:34:30 -0500 Subject: [PATCH 4/6] Move README --- README.md | 156 +--------------------- packages/gatsby-theme-iterative/README.md | 145 ++++++++++++++++++++ 2 files changed, 151 insertions(+), 150 deletions(-) create mode 100644 packages/gatsby-theme-iterative/README.md diff --git a/README.md b/README.md index 4af1694a..612b3d12 100644 --- a/README.md +++ b/README.md @@ -1,152 +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) - - 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 uses it 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 used to - -- 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 - ;[ - 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' - ] -} -``` +For more details about the theme itself, check out its +[README](packages/gatsby-theme-iterative/README.md)! diff --git a/packages/gatsby-theme-iterative/README.md b/packages/gatsby-theme-iterative/README.md new file mode 100644 index 00000000..21d3482f --- /dev/null +++ b/packages/gatsby-theme-iterative/README.md @@ -0,0 +1,145 @@ +## 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 uses it 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 used to + +- 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 + ;[ + 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' + ] +} +``` From 778dd64b40947599160520f95fe520fd02875b82 Mon Sep 17 00:00:00 2001 From: rogermparent Date: Fri, 11 Nov 2022 14:38:46 -0500 Subject: [PATCH 5/6] Finish incomplete item and make postCssPlugins block behave with linter --- packages/gatsby-theme-iterative/README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/gatsby-theme-iterative/README.md b/packages/gatsby-theme-iterative/README.md index 21d3482f..1dae2e9e 100644 --- a/packages/gatsby-theme-iterative/README.md +++ b/packages/gatsby-theme-iterative/README.md @@ -14,7 +14,7 @@ Default: require.resolve('./src/templates/doc.tsx') Will be passed to the `getTemplate` function to use as a default template, the - default function simply uses it if `template` isn't specified. + default function simply returns this if `template` isn't specified. - getTemplate: function @@ -27,7 +27,10 @@ : defaultTemplate ``` - This function will be used to + 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 @@ -58,7 +61,7 @@ Default: ```js - ;[ + const postCssPlugins = [ require('tailwindcss/nesting')(require('postcss-nested')), autoprefixer, require('tailwindcss') From d597f5da6a912dfb63b7d88924f53f61089d0ffa Mon Sep 17 00:00:00 2001 From: rogermparent Date: Fri, 11 Nov 2022 14:52:36 -0500 Subject: [PATCH 6/6] Add main header and intro blurb --- packages/gatsby-theme-iterative/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/gatsby-theme-iterative/README.md b/packages/gatsby-theme-iterative/README.md index 1dae2e9e..b43b3595 100644 --- a/packages/gatsby-theme-iterative/README.md +++ b/packages/gatsby-theme-iterative/README.md @@ -1,3 +1,11 @@ +# 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