|
| 1 | +# Gatsby Theme: Iterative |
| 2 | + |
| 3 | +This Gatsby theme is what [Iterative, inc.](https://iterative.ai) uses to power |
| 4 | +all of our Gatsby websites! It contains all of our shared utility code, as well |
| 5 | +as our full docs engine. This project is still evolving, and while it's |
| 6 | +currently very specific to iterative.ai websites we hope to make it usable for |
| 7 | +others in the future. |
| 8 | + |
| 9 | +## Usage |
| 10 | + |
| 11 | +### Options |
| 12 | + |
| 13 | +- disable: boolean |
| 14 | + |
| 15 | + Default: Boolean(process.env.SKIP_DOCS) |
| 16 | + |
| 17 | + Stops this theme from making pages. Could be used as a conditional for test |
| 18 | + and development purposes. |
| 19 | + |
| 20 | +- defaultTemplate: string |
| 21 | + |
| 22 | + Default: require.resolve('./src/templates/doc.tsx') |
| 23 | + |
| 24 | + Will be passed to the `getTemplate` function to use as a default template, the |
| 25 | + default function simply returns this if `template` isn't specified. |
| 26 | + |
| 27 | +- getTemplate: function |
| 28 | + |
| 29 | + Default: |
| 30 | + |
| 31 | + ```ts |
| 32 | + const defaultGetTemplate = (template, defaultTemplate) => |
| 33 | + template |
| 34 | + ? require.resolve(path.resolve('src', 'templates', template + '.tsx')) |
| 35 | + : defaultTemplate |
| 36 | + ``` |
| 37 | + |
| 38 | + This function will be given the `template` field specified in the page's |
| 39 | + frontmatter, as well as the `defaultTemplate` specified by the option above. |
| 40 | + It is expected to return the absolute path to a React component to be given to |
| 41 | + Gatsby's `createPage` action. |
| 42 | + |
| 43 | +- remark: boolean |
| 44 | + |
| 45 | + Default: true |
| 46 | + |
| 47 | + if true, this theme will add its own instance of `gatsby-transformer-remark`. |
| 48 | + |
| 49 | +- filesystem: boolean |
| 50 | + |
| 51 | + Default: true |
| 52 | + |
| 53 | + if true, this theme will add its own instance of `gatsby-source-filesystem`. |
| 54 | + |
| 55 | +- glossaryPath: string |
| 56 | + |
| 57 | + Default: path.resolve('content', 'docs', 'user-guide', 'basic-concepts') |
| 58 | + |
| 59 | +- simpleLinkerTerms: { matches: string, url: string }[] |
| 60 | + |
| 61 | + Default: undefined |
| 62 | + |
| 63 | + These terms will be passed to `plugins/gatsby-remark-dvc-linker`, which will |
| 64 | + scan code blocks for ones with content matching `matches`, and then link it to |
| 65 | + that entry's `url`. |
| 66 | + |
| 67 | +- postCssPlugins: Plugin[] |
| 68 | + |
| 69 | + Default: |
| 70 | + |
| 71 | + ```js |
| 72 | + const postCssPlugins = [ |
| 73 | + require('tailwindcss/nesting')(require('postcss-nested')), |
| 74 | + autoprefixer, |
| 75 | + require('tailwindcss') |
| 76 | + ] |
| 77 | + ``` |
| 78 | + |
| 79 | + If specified, this array will completely replace plugins this theme passes to |
| 80 | + PostCSS. This is mostly an escape hatch for if styles are broken with the |
| 81 | + default plugins. Check out |
| 82 | + [the theme's `gatsby-config`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/gatsby-theme-iterative/gatsby-config.js) |
| 83 | + to see the default plugins, as not having them in this option will very likely |
| 84 | + break core functionality. |
| 85 | + |
| 86 | +- docsInstanceName: string |
| 87 | + |
| 88 | + Default: 'iterative-docs' |
| 89 | + |
| 90 | + The `name` that will be passed to the `gatsby-source-filesystem` instance for |
| 91 | + docs pages. The resulting `sourceInstanceName` will be used to identify files |
| 92 | + that will be processed as docs pages. |
| 93 | + |
| 94 | +- docsPath: string |
| 95 | + |
| 96 | + Default: path.resolve('content', 'docs') |
| 97 | + |
| 98 | +- glossaryInstanceName: string |
| 99 | + |
| 100 | + Default: 'iterative-glossary' |
| 101 | + |
| 102 | + The `name` that will be passed to the `gatsby-source-filesystem` instance for |
| 103 | + glossary entries. The resulting `sourceInstanceName` will be used to identify |
| 104 | + files that will be processed as glossary pages. |
| 105 | + |
| 106 | +- argsLinkerPath: string |
| 107 | + |
| 108 | + Default: ['command-reference', `ref`, 'cli-reference'] |
| 109 | + |
| 110 | + The path that `plugins/gatsby-remark-args-linker` will operate on, connecting |
| 111 | + arguments listed in the summary with their summaries deeper in the page. |
| 112 | + |
| 113 | +- docsPrefix: string |
| 114 | + |
| 115 | + Default: 'doc' |
| 116 | + |
| 117 | + This is the prefix that the docs pages will render to, including the index |
| 118 | + page at the exact path. |
| 119 | + |
| 120 | +### Examples |
| 121 | + |
| 122 | +See this example from |
| 123 | +[the example website's `gatsby-config.js`](https://github.com/iterative/gatsby-theme-iterative/blob/main/packages/example/gatsby-config.js). |
| 124 | + |
| 125 | +```js |
| 126 | +const path = require('path') |
| 127 | +const { |
| 128 | + name: themePackageName |
| 129 | +} = require('../gatsby-theme-iterative/package.json') |
| 130 | + |
| 131 | +module.exports = { |
| 132 | + trailingSlash: 'never', |
| 133 | + siteMetadata: { |
| 134 | + title: 'Example website', |
| 135 | + description: 'Example website description', |
| 136 | + keywords: ['docs', 'test'], |
| 137 | + siteUrl: 'http://localhost:8000' |
| 138 | + }, |
| 139 | + plugins: [ |
| 140 | + { |
| 141 | + resolve: themePackageName, |
| 142 | + options: { |
| 143 | + simpleLinkerTerms: require('./content/linked-terms') |
| 144 | + } |
| 145 | + }, |
| 146 | + { |
| 147 | + resolve: 'gatsby-source-filesystem', |
| 148 | + options: { |
| 149 | + name: 'images', |
| 150 | + path: path.join(__dirname, 'static', 'img') |
| 151 | + } |
| 152 | + }, |
| 153 | + '@sentry/gatsby' |
| 154 | + ] |
| 155 | +} |
| 156 | +``` |
0 commit comments