Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(recipe):Creating a new site using a theme #20595

Merged
merged 2 commits into from
Jan 14, 2020
Merged

chore(recipe):Creating a new site using a theme #20595

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9873b82
chore(recipe):Creating a new site using a theme
Ekwuno Jan 14, 2020
a91a3c0
Updated Docs according to reviews
Ekwuno Jan 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion docs/docs/recipes/working-with-themes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,79 @@ title: "Recipes: Working with Themes"

A [Gatsby theme](/docs/themes/what-are-gatsby-themes) abstracts Gatsby configuration (shared functionality, data sourcing, design) into an installable package. This means that the configuration and functionality isn’t directly written into your project, but rather versioned, centrally managed, and installed as a dependency. You can seamlessly update a theme, compose themes together, and even swap out one compatible theme for another.

## Creating a new site using a theme

Found a theme you'd like to use on your project? Awesome! You can configure it for use by following the steps below.

> If you'd like to take a look at more theme options, check out [list of themes](https://www.npmjs.com/search?q=gatsby-theme).

### Prerequisities

Make sure you have the following installed:

- [Gatsby CLI](/docs/gatsby-cli)
- [Yarn](https://yarnpkg.com/lang/en/docs/install/#mac-stable)

### Directions

1. Create a gatsby site

```shell
gatsby new {your-project-name}
```

2. Change directory and install theme
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Change directory and install theme
2. Change directory and install theme
In this example, our theme is `gatsby-theme-blog`. You can replace that reference with whatever your theme is named.

Thoughts on doing it this way instead of having the additional example snippet?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha! I agree.


In this example, our theme is `gatsby-theme-blog`. You can replace that reference with whatever your theme is named.

```shell
cd {your-project-name}
npm install gatsby-theme-blog
```

3. Add theme to `gatsby.config.js`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. Add theme to `gatsby.config.js`
3. Add theme to `gatsby.config.js`
Follow the instructions found in the README of the theme you're using to determine what configuration it requires.


Follow the instructions found in the README of the theme you're using to determine what configuration it requires.

```shell
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
/*
- basePath defaults to `/`
- contentPath defaults to `content/posts`
- assetPath defaults to `content/assets`
- mdx defaults to `true`
*/
basePath: `/blog`,
contentPath: `content/blogPosts`,
assetPath: `content/blogAssets`,
mdx: false,
},
},
],
}
```

4. Run `yarn develop` , the theme should be avaliable at `http://localhost:8000/{basePath}`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this we likely need to include yarn installation as a pre-req as well? Or can they run gatsby develop instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add yarn to the pre-req. It's used mostly with themes because of Yarn workspaces.

Copy link
Contributor

@laurieontech laurieontech Jan 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For sure, my question is whether workspaces are necessary for using themes? Or just developing them? The theme starter example uses gatsby develop so figured it was worth double-checking. I don't actually know the answer, so if you're up to test it out that'd be awesome.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think workspaces are necessary for using themes. Also, I saw that running yarn develop triggers gatsby develop.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So let's try using just gatsby develop and if it's successful you can open a new PR making the change and removing the yarn dependency :)

Copy link
Contributor Author

@Ekwuno Ekwuno Jan 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey so I checked and gatsby develop works and I will send in a PR for that . Although I would want to add a note for using yarn install . seems gatsby new keeps the yarn.lock and deleting the package-lock.json file which is then leading to the weird behaviour with running npm install. Can we agree to have this as a note?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I'd love to understand this a bit better. You're saying that when you create a new gatsby project it's creating a yarn.lock file? That shouldn't be the case as gatsby new uses npm. Would love to see what steps you took and where the yarn.lock came into play! I'm not inclined to include any notes about yarn if you don't need to use it in this scenario. I'm wondering if the issues you're seeing are because you already had?

Copy link
Contributor

@muescha muescha Jan 30, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if someone uses before gatsby in combination with yarn, then yarn is used instead of npm.

see https://www.gatsbyjs.org/docs/gatsby-cli#how-to-change-your-default-package-manager-for-your-next-project

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for pointing this out @muescha we fixed it in #20965


> To learn how to further customize a theme,check out the avaliabe paths on [Gatsby-theme-blog Documentation](https://www.npmjs.com/package/gatsby-theme-blog).

### Additional resources

- To learn how to further customize a theme, check out the docs on [Gatsby theme shadowing.](https://www.gatsbyjs.org/docs/themes/shadowing/)

- You can also [use multiple themes](https://www.gatsbyjs.org/docs/themes/using-multiple-gatsby-themes/) on a project.

## Creating a new site using a theme starter

Creating a site based on a starter that configures a theme follows the same process as creating a site based on a starter that **doesn't** configure a theme. In this example you can use the [starter for creating a new site that uses the official Gatsby blog theme](https://github.com/gatsbyjs/gatsby-starter-blog-theme).

### Prerequisites

- The [Gatsby CLI](/docs/gatsby-cli) installed
- Make sure you have the [Gatsby CLI](/docs/gatsby-cli) installed

### Directions

Expand Down