This course has been updated! We now recommend you take the Intermediate Gatsby, v2 course.
Transcript from the "Install a Theme" Lesson
[00:00:00]
>> Jason Lengstorf: At this point, I wanna jump into a real site. I wanna jump into a working site. So we're going to open up the Honkify site. And that will already be installed in your,
>> Jason Lengstorf: Code editor here, so we can just close up the packages. We're gonna be working in Honkify.
[00:00:21] So just take a look at it. It's got an index.mdx, so it's already using mdx. And let's just boot it up and take a look, yeah? So we do yarn workspace honkify develop
>> Jason Lengstorf: Okay, so we've got a marketing page for our library. This is a very important, very useful JavaScript library that I would encourage all of you to install today.
[00:01:00] What it does is when you turn it on, it will make sure that your browser honks instead of following links. I wanna add documentation to this site. So I've built a library. I've got a homepage. Everybody loves it, everybody wants to use it, but we haven't added docs yet.
[00:01:16] So I don't wanna have to reinvent docs from scratch. I wanna install a theme. So what I can do is I can just install this theme. So we're going to stop the server. And I will install the theme using yarn workspace honkify add. And then because we're installing a local theme, I'm gonna put it in quotes, "gatsby-theme-docs@*".
[00:01:51]
>> Jason Lengstorf: Okay, all good. Then I'm going to actually configure it in my gatsby config. And so to do that, I'm just gonna go down and we'll stick it right above gatsby plugin theme UI. Order shouldn't matter here. I didn't test it. And I'm not gonna tempt fate. So let's put it where I put it last time.
[00:02:18] We're going to install it here. We're going to set some options on the theme this time because we already have a homepage, right? So we want our docs to live at slash docs, not at like the root of the site. So I'm gonna set a base path of docs.
[00:02:34] And I'm gonna deal with with a leading slash there. And then because we already have MDX installed, I'm gonna say that I do wanna use external MDX.
>> Jason Lengstorf: And once that is installed, what I can do is let's see.
>> Jason Lengstorf: Let's just start it up and see how it goes.
[00:02:59] So yarn workspace honkify develop. And in honkify, we've already got. To avoid having to create a bunch of files, I just created some empty docs files here for us to work with. And looks like something broke.
>> Jason Lengstorf: I missed a comma.
>> Jason Lengstorf: Try that one more time with the comma in place.
[00:03:42]
>> Jason Lengstorf: Okay, the site's running.
>> Jason Lengstorf: No errors.
>> Jason Lengstorf: Okay, and so if we come out here and we look, nothing is visibly changed, but what happens if I go to Docs? And I didn't create an index page. So let's go to doc/installation. Okay, so our theme works, but it's not quite right.
[00:04:09] It's picking up the colors but it's not picking up the theme. So we're gonna use component shadowing to tell the Docs theme to use the layout from honkify. So let's hop in here and in the source folder, I'm going to create a new file and it's gonna live in gatsby-theme-docs.
[00:04:32] And once we go into gatsby-theme-docs, again, what we're doing when you're component shadowing is by targeting this folder, we get access to the full source folder inside of the theme. So we don't include the source. We just go straight into whatever's in there. So we wanna get at the components.
[00:04:50] And I wanna change layout.js. So now, what will happen is when I restart the server, the docs theme is gonna pick up this file. So if I did it right now, it would fail because it's not a react component. So what I'm gonna do instead is I'm gonna import layout from, let's get up the tree here, and I'm gonna get components/layout.
[00:05:12] And then I'm going to export default layout. So effectively what I've just done is I've said, hey, docs theme, use this layout component instead. And so it will replace that for us. So let's make that happen.
>> Jason Lengstorf: And upon getting started up, what we should see when we refresh the page is that now, our docs still work but they've picked up the layer from our site.
[00:05:45] So without having to make any changes to the theme itself, our theme files now look like they belong on this site. And when we move around, it looks like it's all part of the same site. So this is where we start to see the power of gatsby themes.
[00:06:00] We did, what eight lines of code and we've got a fully functional doc section on the site now that we built it. That's a really powerful model that gives us a lot of power when we get into it. The next thing that we wanna do is I want to be able to use this button, right?
[00:06:18] We've got this button I wanna be able to use that in a live editable region. So what I'm gonna do is I'm going to create a scope.js and now we're gonna overriding that scope.js inside of the theme. And I can import the button from components/button. And then I'm gonna export default.
[00:06:42] And I just want the button to be available.
>> Jason Lengstorf: And to test this, let's stop and restart. And I'm gonna go into the docs and let's add in an editable block. So we're gonna setup jsx, make it react-live and I want to export a function. So I'm gonna write a custom click handler for it.
[00:07:16] And that will just be that alert that we did before.
>> Jason Lengstorf: And we will return a fragment that's got a heading. And then we will use our button. So we're not importing the button, we already put it in the scope. That means that we can use it. So I'm gonna set up some text.
[00:07:40] Our text is gonna be honk. And the onClick is going to be our handle click function that we just wrote. Okay, so, assuming all has gone well, when I save this, get back out. I forgot to close my fragment. But we can see here, it caught that for us.
[00:08:01] It told us that we screwed it up, right? So now, once I close this up, come back out here. There we go. Okay, so it clicks. And what's even more fun is if we activate honkify, [SOUND] it works. It interacts with the page, right? So this is a really, really nice way to set up interactive examples and allow people to play so that they can see how things work in real time and edit.
[00:08:30] And I think the last thing that we need to do, [SOUND] whoops. [LAUGH] Is we just need to add a link to it. So if we go into our pages, we can just duplicate this and say, read the docs. And we'll just skip right through to that installation.
[00:08:52] So now on our homepage, we've got a link to the docs. And in what, took like five, ten minutes. We just set up an entirely new doc section on an existing site that looks like it belongs on this site. And so I think this is where you start to see the power of gatsby themes and why there's such a powerful abstraction.
[00:09:11] Cuz we did all of that pain of setting up the config and diving through the GraphQL Schema customization, and making sure that the docs folders created. All that work, and the end result is we get plug-and-play drop in stuff like this. It's really really nice experience when you start using the theme as opposed to building it.
[00:09:32] So let's save our work. And then, I wanna see how it feels to create a new site using the theme. Where am I going, here we are. So we're gonna do a git add all. Check the status. And we've got our modified installation instructions, we set up the theme, installed the theme, shadowed the layout and the scope, and updated the home page.
[00:09:59] So let's commit
>> Jason Lengstorf: Okay, let's get that pushed up.