I deployed my first Theme demo on Netlify and I'd like to document how I've done it.

I think it's pretty straight forward but probably worth-it to write about it.

The setup is using yarn workspaces and the demo page will be located in the demo directory.

You can have a look at github/awolf81/gatsby-theme-mdx-demo for the project setup.

Configure Netlify

First, connect your Github repository to Netlify by login into Netlify and click on New site from Git on the Sites page.

Choose Github for Continous Deployment (later also CD).

Pick the project from the list or the link below Configure the Netlify app on Github if you're not seeing your project.

Now select All repositories or limit access to some of your repositories. I'm using just the repositories that I'd like to deploy with Netlify but it's probably also OK to allow all repos. Because only the projects that you're adding with the New... button on Netlify will be added to use continuous deployment.

No other setup needed as we're using a netlify.toml file in the repository just linking the repo is enough.

Configure your repository

Add a netlify.toml file with the following configuration to the root of your project:

[Build]
  Publish = "demo/public/"
  command = "yarn workspace demo build"
  Functions = ""

[Build.environment]
  NODE_ENV = "PRODUCTION"

This will tell Netlify that we'd like to run the build script of the demo workspace and to use the public path from the demo workspace.

Next, we have to add the build script to demo/package.json so that the build will be triggered.

So add the following to package.json of demo workspace:

{
  ...
  "scripts": {
    "build": "gatsby build"
  }
}

Now stage every change, commit it to Git and push to Github. This push will automatically trigger a CD and you can check the build in the Netlify web app.

If everything is working as expected you should see a published badge (see below) on the last build in Deploys panel. If not click on the deploy and check the error message.

Deploying multiple workspaces

If you'd like to deploy two or more demos (e.g. demo-basic & demo-advanced) you have to remove the netlify.toml and do the configuration manually in the Netlify web app.

Why would you want multiple demos? I think it's good to have a minimal demo and one that is using every feature of your theme and maybe also other optional themes.

Removing the TOML file is required because it would override the settings from the Netlify configuration that was added in the app.

There is an open issue about the problem but no fix at the moment.

Netlify is just using the netlify.toml in the root directory and not respecting/handling TOML files in sub-directories.

So the only work-around I've found is to create different sites in the Netlify app and add the configuration manually like following:

Not a great solution but it is working - ideally, this could be created from the TOML and also do an URL handling with the configuration e.g. URL gatsby-theme-mdx-demo.netlify.com/demo-basic/ or gatsby-theme-mdx-demo.netlify.com/demo-advanced/

For the workaround, there will be a site in the Netlify app for each workspace. You can add the same repository multiple times to Netlify as new site and customize the build so it's building the correct demo.

Base directory will change the working directory to demo-basic and then run gatsby build.

Public directory is still referenced from the root folder that's why we have to add the demo-basic to the path.

Final tweaks

You probably want to change the site name. You could also use the generated name but it's difficult to remember. For renaming go to the Settings tab and there in General\Site details click Change site name. Pick an available name for your page e.g. gatsby-theme-your-theme-name-demo.

Now you can check your deployed demo at this page https://gatsby-theme-your-theme-name-demo.netlify.com.

The deployment of my demo can be found here. Maybe I'm adding some styles to the demo soon so it's looking nicer. But adding an automatic navigation generation to the theme would be probably better and more fun to build.

If you have registered a custom domain you could also go to Domain management and click Add custom domain. Then you can access the deployment with your-domain.com