diff --git a/packages/gatsby-plugin-theme-ui/README.md b/packages/gatsby-plugin-theme-ui/README.md
index 4d3e09103..21662d17a 100644
--- a/packages/gatsby-plugin-theme-ui/README.md
+++ b/packages/gatsby-plugin-theme-ui/README.md
@@ -18,14 +18,14 @@ prevent a flash of unstyled colors when using color modes.
 
 ## Options
 
-| Key                      | Default value    | Description                                                                      |
-| ------------------------ | ---------------- | -------------------------------------------------------------------------------- |
-| `prismPreset`              | `null` | The name of the preset you'd like to use to style code blocks inside your markdown files. The available presets can be found in the [theme-ui docs](https://theme-ui.com/packages/prism/). You can also use a package string of your own choosing. |
-| `preset`               | `null`            | This can be a JSON theme object or a string package name. Make sure the package you're requiring is installed in your dependencies.               |
+| Key           | Default value | Description                                                                                                                                                                                                                                        |
+| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prismPreset` | `null`        | The name of the preset you'd like to use to style code blocks inside your markdown files. The available presets can be found in the [theme-ui docs](https://theme-ui.com/packages/prism/). You can also use a package string of your own choosing. |
+| `preset`      | `null`        | This can be a JSON theme object or a string package name. Make sure the package you're requiring is installed in your dependencies.                                                                                                                |
 
 > Note that this plugin assumes the theme object is exported as `default`.
 
-The theme module you include in options is considered your base theme. Any further customization and shadowing will be merged with it. 
+The theme module you include in options is considered your base theme. Any further customization and shadowing will be merged with it.
 
 ### Using options
 
@@ -49,8 +49,7 @@ module.exports = {
 To customize the theme used in your Gatsby site,
 shadow the `src/gatsby-plugin-theme-ui/index.js` module.
 
-```js
-// src/gatsby-plugin-theme-ui/index.js
+```js filename=src/gatsby-plugin-theme-ui/index.js
 export default {
   colors: {
     text: '#111',
@@ -59,12 +58,40 @@ export default {
 }
 ```
 
+### Load theme from custom path
+
+If you prefer to load your theme from a custom path (instead of the standard `src/gatsby-plugin-theme-ui/index.js`),
+you can require it in your `gatsby-config.js` file:
+
+```js filename=gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: 'gatsby-plugin-theme-ui',
+      options: {
+        preset: require('./src/theme'),
+      },
+    },
+  ],
+}
+```
+
+Note that `gatsby-config.js` does not support ES6 modules, so you should use `module.exports` in your theme file:
+
+```js filename=src/theme.js
+module.exports = {
+  colors: {
+    text: '#111',
+    background: '#fff',
+  },
+}
+```
+
 ## Extending a theme
 
 To extend a Gatsby theme that uses Theme UI, import the base theme and export a new theme object.
 
-```js
-// src/gatsby-plugin-theme-ui/index.js
+```js filename=src/gatsby-plugin-theme-ui/index.js
 import baseTheme from 'gatsby-theme-blog/src/gatsby-plugin-theme-ui'
 
 export default {
@@ -83,8 +110,7 @@ You can also import and use presets from [@theme-ui/presets](https://theme-ui.co
 
 To enable support for multiple color modes, add a nested `modes` object to `theme.colors`.
 
-```js
-// src/gatsby-plugin-theme-ui/index.js
+```js filename=src/gatsby-plugin-theme-ui/index.js
 export default {
   colors: {
     text: '#000',
@@ -103,10 +129,9 @@ export default {
 
 Custom MDX components that will receive styles from the theme can be included by adding a `src/gatsby-plugin-theme-ui/components.js` module.
 
-```js
-// src/gatsby-plugin-theme-ui/components.js
+```js filename=src/gatsby-plugin-theme-ui/components.js
 export default {
-  h1: props => (
+  h1: (props) => (
     <h1 {...props}>
       <a href={`#${props.id}`}>{props.children}</a>
     </h1>