PBS_2025_03_01
An audio podcast where Bart Busschots is teaching the audience to program. Associated tutorial shownotes are available at https://pbs.bartificer.net.
Automatic Shownotes
Chapters
0:10
Introduction to Jekyll and GitHub Pages
2:17
Installing Ruby and Jekyll
4:40
Understanding GitHub Pages Configuration
6:54
Jekyll Setup and Source Management
9:58
Installing Ruby Versions with chruby
13:43
Ruby Gems and Bundler Basics
15:50
First Steps with Jekyll
16:07
Creating a GitHub Repository
18:28
Setting Up Your Docs Folder
19:51
Jekyll Configuration and Markdown
26:24
Testing Jekyll Locally
31:11
Running Jekyll and Viewing Changes
34:39
Preparing for GitHub Deployment
38:49
Building a Basic Jekyll Theme
41:58
Customizing Bootstrap in Jekyll
45:47
Finalizing the Theme for Deployment
51:35
Managing Assets and Dependencies
58:39
Adding Interactive Elements with Bootstrap
1:06:21
Introduction to Jekyll's Liquid Templating
1:10:35
Finalizing the Theme and Testing
1:16:09
Ready for Content and Future Enhancements
Long Summary
In this episode of Programming by Stealth, we dive into installment 177, where I, Alison Sheridan, along with my co-host Bart Bouchotts, embark on an extensive educational journey focused on GitHub Pages and Jekyll. This marks the third installment in our series, where we've already established the foundation — from understanding the overarching concepts of GitHub Pages to exploring how GitHub Actions can streamline deployment processes.
We begin by exploring the prerequisites needed to successfully run Jekyll on our local machines, emphasizing the necessity of having Ruby installed. This time, we install Ruby 3.x and address common pitfalls experienced when installing it, especially for those using macOS, which often comes pre-installed with an older Ruby version. We also guide listeners on using Homebrew and a utility called chruby to manage multiple Ruby versions seamlessly.
The crux of our discussion revolves around setting up a basic Jekyll site. A distinction is made between the convenience of running GitHub Pages and the need for a local development environment, where we can test everything before pushing updates online. We detail the importance of a clean setup — highlighting the necessary file structures, including the gems file and directories for configurations. I learned along the way the critical importance of following instructions precisely, demonstrating how simple oversights can lead to a cascade of errors.
We delve into creating a Jekyll-based site from scratch, covering everything from creating a repository on GitHub to configuring essential files like `config.yml` and `Gemfile`. The process is laden with simple yet vital commands and installations, each explained thoroughly to ensure listeners can replicate the steps with ease. I share my personal experiences, admitting the trials and errors I faced, underscoring the lesson that understanding the nuances of building a static site with Jekyll is essential for avoiding pitfalls later.
We then shift our focus to customizing our Jekyll site using Bootstrap, elaborating on how to incorporate Bootstrap's compilation process using SASS. I express my initial reluctance towards handling source files, but Bart reassures me that flexibility is one of the benefits of using Bootstrap. Together, we establish essential configurations and directory structures required for styling, emphasizing the importance of separating our assets.
As we round off the discussion, I’m excitedly challenged with understanding how to manage variables and imports within SASS as part of the customization process. We share the particular joys of making our themes adaptable and robust, using Jekyll's templating language, and Bart highlights essential coding practices and tips that lead to successfully launching our newfound creations to the web.
Our goal is not only to complete a seemingly simple website but to iteratively learn how to enhance our Jekyll projects. I end the episode anticipating future lessons, which will involve deepening our understanding of themes and content creation within Jekyll, while remaining committed to applying what we have learned in real-time development.
We begin by exploring the prerequisites needed to successfully run Jekyll on our local machines, emphasizing the necessity of having Ruby installed. This time, we install Ruby 3.x and address common pitfalls experienced when installing it, especially for those using macOS, which often comes pre-installed with an older Ruby version. We also guide listeners on using Homebrew and a utility called chruby to manage multiple Ruby versions seamlessly.
The crux of our discussion revolves around setting up a basic Jekyll site. A distinction is made between the convenience of running GitHub Pages and the need for a local development environment, where we can test everything before pushing updates online. We detail the importance of a clean setup — highlighting the necessary file structures, including the gems file and directories for configurations. I learned along the way the critical importance of following instructions precisely, demonstrating how simple oversights can lead to a cascade of errors.
We delve into creating a Jekyll-based site from scratch, covering everything from creating a repository on GitHub to configuring essential files like `config.yml` and `Gemfile`. The process is laden with simple yet vital commands and installations, each explained thoroughly to ensure listeners can replicate the steps with ease. I share my personal experiences, admitting the trials and errors I faced, underscoring the lesson that understanding the nuances of building a static site with Jekyll is essential for avoiding pitfalls later.
We then shift our focus to customizing our Jekyll site using Bootstrap, elaborating on how to incorporate Bootstrap's compilation process using SASS. I express my initial reluctance towards handling source files, but Bart reassures me that flexibility is one of the benefits of using Bootstrap. Together, we establish essential configurations and directory structures required for styling, emphasizing the importance of separating our assets.
As we round off the discussion, I’m excitedly challenged with understanding how to manage variables and imports within SASS as part of the customization process. We share the particular joys of making our themes adaptable and robust, using Jekyll's templating language, and Bart highlights essential coding practices and tips that lead to successfully launching our newfound creations to the web.
Our goal is not only to complete a seemingly simple website but to iteratively learn how to enhance our Jekyll projects. I end the episode anticipating future lessons, which will involve deepening our understanding of themes and content creation within Jekyll, while remaining committed to applying what we have learned in real-time development.
Brief Summary
In this episode of Programming by Stealth, I, Alison Sheridan, along with my co-host Bart Bouchotts, continue our educational series on GitHub Pages and Jekyll. We focus on the prerequisites for running Jekyll locally, emphasizing the installation of Ruby 3.x while addressing common issues for macOS users.
We guide listeners through setting up a basic Jekyll site, discussing the differences between working with GitHub Pages and having a local development environment. I share insights from my personal experience on the importance of precise instructions to avoid errors.
The episode covers creating a Jekyll site from scratch, including repository creation and necessary file configurations such as `config.yml` and `Gemfile`. We also explore customizing the site using Bootstrap and SASS, tackling the challenges of managing source files and coding practices. As we conclude, we look ahead to future lessons on themes and content creation, committed to applying our knowledge in real-time development.
We guide listeners through setting up a basic Jekyll site, discussing the differences between working with GitHub Pages and having a local development environment. I share insights from my personal experience on the importance of precise instructions to avoid errors.
The episode covers creating a Jekyll site from scratch, including repository creation and necessary file configurations such as `config.yml` and `Gemfile`. We also explore customizing the site using Bootstrap and SASS, tackling the challenges of managing source files and coding practices. As we conclude, we look ahead to future lessons on themes and content creation, committed to applying our knowledge in real-time development.
Tags
Programming by Stealth
Alison Sheridan
Bart Bouchotts
GitHub Pages
Jekyll
Ruby 3.x
macOS
Jekyll site
Bootstrap
SASS
themes
content creation
Transcript
[0:00]Music
[0:10]
Introduction to Jekyll and GitHub Pages
[0:07]Well, it's that time of the week again. It's time for Programming by Stealth. And this is installment 177, recorded March 1st, 2025. And I'm your host, Alison Sheridan. And of course, I'm joined by our lovely co-host, Bart Bouchotts. Hi, Bart.
[0:20]Hi, Alison. Always lovely to be with you. And isn't it nice that now that we're not merging this into Chit Chat Across the Pond, you don't have to remember two show numbers?
[0:30]It definitely is. And I'm sure everybody else is happier, too.
[0:35]It is simpler, yes.
[0:37]Well, I have to say to the audience that it is a really good thing that I went through the show notes offline, did all the exercises offline, because it took me at least two hours to go through this. And not because Bart's instructions aren't fabulous, because they really are. They're very clear. They're very concise. But you have to do exactly what he says. If he says move the contents of a folder, he doesn't mean move the folder. If he says this is what the file name should be, the file name should be that, not the one you dragged in that he told you to drag in. You have to rename it to exactly what he says. And don't leave another one over there that has a similar name. Don't do that either. So I made a lot of mistakes. And right when I was like, oh, there's the mistake. It was always me.
[1:24]And another thing, of course, is we are installing Ruby and stuff this time. So even if you follow them exactly perfectly, on an m4 mac it'll be pretty quick but on an older mac it'll take a while.
[1:38]Ah okay yeah there's a whole lot of stuff i don't know anything about going on here where you're just kind of like okay we're going to install this install this install this but then trust me then we're going to know what we're doing and so without like really grokking a lot of it sometimes it's easy to miss something you said so uh like i said the show notes are spectacular, as always, but the student had a little trouble.
[2:00]Yeah, but it's good, right? Because you've found the little pitfalls, and you can highlight them to the listeners and say, see that over there? That's a pothole. Don't step in it.
[2:10]Exactly, exactly. I may have bolded a few words of yours to go, no, he really means the contents.
[2:17]
Installing Ruby and Jekyll
[2:17]All right, let's get started.
[2:19]So this is the third installment of our series on GitHub Pages. We started off with a really big picture overview, and then we took a little diversion to learn how to use GitHub Pages and GitHub Actions to build a webpack-based app. And now we are going back to using GitHub Pages in its default configuration, which uses a static site generator called Jekyll, which is open source excuse me and because we're using the default setup for github pages we don't have to write our own github our github actions to do the deployment because we're now in default land so we get it for free so we just basically say do github pages do what you'd like to do and away we go nice yes but where we have heavy work to do is on our own computer because we'd like to live in a world same world we lived in last time where we were able to test everything locally in that case using webpack locally verify it's all working and then push the working codes up to git and have it deployed to github pages and if we want to do the same with jekyll then And we have to be able to run the Jekyll static site builder on our computers.
[3:42]And so we run it locally. We test it. We get everything working right. And then we push to Git and off it goes onto the internet.
[3:53]Now, Jekyll is written in a language called Ruby, which means we need to have Ruby installed in order to run Jekyll. So all of that stuff that GitHub is doing by default and that GitHub action we didn't have to write, we have to mirror it on our local computer.
[4:13]So once we have Ruby installed, it's going to be installed everywhere on our computer. So if we wanted to do something, you're going to have us build a little website on actually a CMS locally here. But if we want to go build another one, we don't have to install Ruby again, right? Now we have Ruby. Right.
[4:30]Yes, exactly. So all of this work you do now, it'll be way, way quicker on your second site, your third site, your fourth site, your fifth site,
[4:40]
Understanding GitHub Pages Configuration
[4:39]because everything will be there. You're just basically linking to it in each of the docs folders and i won't be installing it fresh it'll just it's a bit like installing node.js once well now you have it you know so you're away right now um okay so we mentioned in our introductory installment that with github pages what we're doing is we are putting our source codes into the docs folder and then that's going to be converted into a web page by Jekyll, the static site builder, and that's what gets published onto GitHub Pages. Now, GitHub Pages uses Jekyll, but it's open source, and one of the things you're allowed to do with open source is customize it. So GitHub Pages actually uses the GitHub Pages flavor of Jekyll. And so they customize it a little bit. So they're always a little bit behind.
[5:41]Because they don't take the very, very latest cutting edge Jekyll and customize it. They take a stable one from a while ago and customize that one. And then every now and then they'll jump forward. But in the meantime, they'll keep their version secure, but they're not necessarily getting every latest update. So you just have to be cognizant of that fact. So to us, the latest version of Jekyll is 3.10.
[6:11]To Jekyll, the latest version of Jekyll is 4.3. Their documentation is really good. So any feature that's new has a little note saying introduced in version blah. So if it says introduced in 4.1 or 4.2, not for us. So we're going to be installing an.
[6:32]Older version of Jekyll.
[6:34]Yes. In fact, we're not going to install Jekyll explicitly. We're going to install github pages and it has a dependency that is jekyll and it will fetch the version of jekyll it wants and use that one so we're letting
[6:54]
Jekyll Setup and Source Management
[6:51]github pages do the work even though it's local if.
[6:54]You hadn't told us that how would we have known
[6:56]The documentation for github pages tells you there's a there's a page you go to in their docs that lists every version of every dependency so they say when you install github pages you get these i think it's 30 packages so it's every different version number is there so you can tell which version of the cram down markdown generator is used which version of sas is used which version of everything so they list it all okay.
[7:23]Okay do do um is it appropriate to say that jekyll is like wordpress
[7:34]Yeah, it's a different mechanism of solving the same problem.
[7:38]Okay, but it isn't a content management system.
[7:42]No, it is. It's just not a database-driven one.
[7:45]Yeah, okay, good. I mean, I know we went through it before, but now that we're actually doing it, I want to put it somewhere in my head that that's what Jekyll is. Okay, because for the longest time, I always thought Jekyll was the theme you were using, and I could never get like, what is he talking about? But okay, that makes more sense.
[8:00]All right, I'm up to speed. Okay, so in order for us to run Jekyll locally, we need Ruby. In fact, we need Ruby version 3. And Apple, for reasons I don't understand, still ship an ancient version of Ruby 2. So to get Ruby 3, now, there's lots of bad instructions on the internet. And they tell you to replace Ruby version 2. macOS does not like that. Oh, so it's using it somewhere? Yeah. Yeah, under the hood, it's still in there. and other app developers are assuming your Mac is not weird.
[8:39]So if you have another app that's built on Ruby under the hood, if you go and rip out Ruby 2, I don't want to be responsible for the side effects. So we're going to add a version of Ruby 3 side by side, nice and safe, we're not going to break anything. And the easiest way, as with so many things, is to use Homebrew, our absolute best friend. So if you don't already have Homebrew, you need to install that. First, the instructions on their homepage are trivially simple. So away we go. Then once we have our two versions of Ruby installed, we need an easy way to toggle our terminal between the different Rubies that are now on the system. And there's a really useful utility that's also open source called chruby, chruby. So like chdir for change directory, chmod for change permissions, so chruby is change ruby. And so you can use chruby to toggle between the different versions as you're typing.
[9:41]So if you think about it, a script has a shebang line that says what version it wants. But the terminal has to default to something for when you don't tell it which Ruby you want. And so that's what Shruby changes. So it won't break any scripts or anything because they'll have their own shebang
[9:58]
Installing Ruby Versions with chruby
[9:57]line saying what they want. But your terminal needs a chooser because you now have two options. And Shruby is the way we're going to do that choosing. Oh, you're on mute, Alison.
[10:12]Sorry, opened a drawer and didn't want to make noise. So we're going to install to Ruby and then use to Ruby to install Ruby? Yes.
[10:22]Yes, because... No, we're going to use to Ruby to fetch the Ruby we want. And in theory, we could have five different versions of Ruby 3. So you can imagine that you're building one website with Jekyll and another website with something else. And the something else wants Ruby 3.2 and Jekyll wants Ruby 3.3. And some other thing wants Ruby 3.4. You can do as many as you want with Shruby. So you can solve every dependency, without having a fight because that's developer hell, right? I have one app I'm working on in one folder that needs Ruby whatever and another app in another folder that needs a different Ruby. Now they're fighting with each other. But with Shruby, there are no fights. You just say, yeah, Shruby, fetch all the Rubies I want. They'll all live side by side in perfect harmony and my terminal will default to one, but each folder can do whatever it wants because it just uses a shebang line.
[11:17]The folder uses it.
[11:19]As in whatever project you're working on, the project is going to take care of that.
[11:24]Having been through these instructions, I don't remember us ever telling it which version we were going to... Oh, yes, I do. Never mind. I do remember.
[11:31]I was going to say second command. So our first command is to install two things. We're installing Shruby and the universal Ruby installer. So we're going to say brew install shruby space ruby dash install. Oh, so that's two installs. So that's going to fetch two brews. Yes.
[11:50]Oh, I thought, I didn't understand why that was two things. Okay, great.
[11:54]Yes. And then, actually, it's Ruby install, sorry. Yeah, so it's not shruby that installs the other one, it's ruby install that installs the other one, which makes more sense. My apologies. Okay. So our second command calls the newly installed ruby install to install Ruby version 3.3.5, and you did or didn't do that. What did we decide on in the end?
[12:14]I boy that's i thought it was 3.4.1 did we lose that change
[12:19]No the change isn't in the show notes right now but yeah i did it with 3.3.5 back in february no i did this in january and you did it today with 4 3.4.1 so show notes will say 3.4.1 you.
[12:36]Lost my change some changes so this is going to be scary because i 100
[12:40]No no i haven't made a single change so i think you may have forgotten to commit that because all of your changes are there you can anyway you can look at the change log to prove it but i definitely didn't i didn't f didn't undo i'd asked i think i asked you to undo and you said you'd undo and then if nothing broke you'd put it back and obviously nothing broke okay anyway the show notes will be right okay so once you have excuse me once you have all that installed we need to add a few little things into our terminal so there are just a few commands that update our zsh orc file which is the equivalent of the old bash orc from bash universe, and then we are ready to go. And we can prove we're ready to go by saying Ruby minus minus version and it'll tell us that we're on the version we think we installed.
[13:39]Yes.
[13:43]
Ruby Gems and Bundler Basics
[13:41]Right. Now, Ruby...
[13:43]By the way, for the audience, that was a whole lot of Truby, Ruby install, Ruby install, Ruby, Truby. It'll make sense when you see it in the show notes.
[13:51]It's also five commands, so it's not too bad. Now, this is where we have a little bit of terminology to learn. So in JavaScript, we have packages, so we'd use npm to install a package. In Ruby, everything is a pun on gemstones, because Ruby is a gemstone. So Ruby doesn't call its packages packages, it calls its packages gems, which is way cooler. So you buy this little jewel, or you download this little jewel of someone else's code. It's your gem. Okay. So you use gems to manage things, and there's a Ruby equivalent of NPM, which is called Bundler. So we're going to use the gem command to install the Bundler command, which is going to install all of our other gems, just to confuse you completely.
[14:53]Okay. yeah i didn't follow that at all but if i i typed in what you said to type in and it did a bunch of stuff
[15:01]Yeah so gem installs one pack one package at a time bundler is way more intelligent and just gets all the dependencies so bundler is like so we're going to tell bundler to install github pages which actually needs 30 dependencies if we were doing that with gem we'd have to do 30 commands, but when we do it with bundler it does all that for us and just gets all the gems in one command okay.
[15:30]So we are going to use gem to install jekyll we're going to use bundler to install jekyll but we had to use gem to install bundler
[15:37]Yeah clear as mud yeah i know, Right.
[15:42]Okay.
[15:43]I'm not the world's biggest fan of Ruby. This is one of the reasons,
[15:50]
First Steps with Jekyll
[15:47]because I'm now completely lost in this circle of logic here. But anyway, it works, it works, it works. So, our first work example today...
[15:55]So we have not installed Jekyll yet.
[15:57]No. All we have done is get our system ready.
[16:00]Okay.
[16:01]So we now have... I want you.
[16:02]To raise your hand when we're actually installing Jekyll. Tell me that,
[16:07]
Creating a GitHub Repository
[16:05]because I want to make sure I don't miss it.
[16:08]Right now. So our first worked example is to get a Jekyll-based website with customizer Bootstrap open running. So that's what we're going to start doing right now. So the first step is to make a repository on GitHub. We're going to clone that locally, and then we're going to do our first bit of Jekyll-ing.
[16:30]Okay, it's quite a ways after these two steps.
[16:32]Yeah, I was just going to say.
[16:33]We aren't there yet.
[16:34]It's step four, yeah. Right, okay. So we need to create a repository uh this is very much exactly what we did last time so you're going to go into github make a new repository assuming you're not paying for a paid subscription you're going to have to make it a public repository because otherwise github pages won't work if you're a paid github user you can keep your repository private and still have github pages but i figured let's not assume our listeners are spending money because the free tier on github is great i'm.
[17:07]Wondering whether somebody's going to notice why did a whole bunch of repos just create to create a uh or a whole bunch of people just create these repos called pbs 177 what yeah that must be cool i must need that too look at it it's spiking
[17:23]Trending repositories. Ooh, lots of forks, yeah. Interesting. Good point. Okay. So the next thing is I strongly recommend you tick the box that says to add a readme because that way you don't have to do an initial commit. That easier initial commit, it just makes it a bit easier to clone your repository. And then to save yourself faffing about, let GitHub add an ignore file for Jekyll. So you can choose what type of ignore file you'd like and it's a search box so if you type in jekyll it has a pre-made ignore file for jekyll so just pick that one one that will well that adds a doc get ignore file that ignores stuff like the underscore site folder which is for local testing you don't want that to come into git okay.
[18:13]I don't know
[18:14]What the other so like when When we're working with Node.js and you don't commit the Node.packages folder, because that's your local copy, when we're working with Jekyll, there are files that are not part of our source code,
[18:28]
Setting Up Your Docs Folder
[18:27]they're part of the output. You don't commit those to Git, because they're supposed to get built by GitHub pages, you're not supposed to give it the output.
[18:36]Okay. Okay, so it's not the Jekyll software that we're telling it to ignore. Or we're telling it files?
[18:47]It is. We're telling it the only thing to be kept in GitHub is our source code. That's the bit we version. We don't want to be versioning Jekyll. Jekyll exists. Jekyll will be fetched by the GitHub Action to publish the GitHub pages. We have Jekyll installed. So you don't publish every NPM package you use when you're saving your code. You're just saving your code.
[19:16]This is going to get back to me not being able to recognize what in this folder when we're done is Jekyll. So when we get there, I'll keep asking this question. You do, please.
[19:27]This is a point that is non-obvious. It will become habit, but it's not, oh yeah, that's easy. It's okay, I got to ingest this. Okay. So yeah. Okay. So once you have your repo, clone it to your computer and open a terminal in that new, fresh repository.
[19:51]
Jekyll Configuration and Markdown
[19:51]So we are going to be working in the docs folder. So let's make a docs folder and change into it. So two commands in one, mkd or docs, semicolon, cddocs. So that's two terminal commands on one line because I'm lazy.
[20:09]And so Jekyll is a Ruby app. And Ruby apps use a file. So you know the way when we were using Node.js, we had package.json and that's how Node.js knew what packages it needed. The Ruby equivalent is called gem file and it's a file that tells Ruby what Ruby gems you are going to use. And so that file is going to say that we want to use GitHub pages, which is going to go and fetch Jekyll for us. So that file is how we tell Ruby what we're going to use in this docs folder. And we could make the file manually, but that's not the right thing to do. So where we would say npm init, the equivalent now in Ruby universe is bundle init. And that will make docs forward slash gem file with a capital G come into being.
[21:16]Okay.
[21:18]Then because we're using Ruby 3, there is a Ruby gem that was a completely default part of Ruby 2. And for reasons I don't understand, it became an optional extra in Ruby 3. So we have to now manually install it. And we do that by saying bundle add webrick, W-E-B-R-I-C-K. Do we care what Webrick is? It's a thing for doing HTML stuff that Jekyll needs and that used to be part of Ruby and now is an optional extra.
[21:57]Got you. Okay.
[21:58]And so that's equivalent to doing npm install jQuery. Instead, it's bundle add Webrick.
[22:06]Gotcha. Okay.
[22:07]And that will actually edit the gem file. If we peep inside the gem file, you'll see a line appears saying, We want to use Webrick at whatever version it happens to be at.
[22:17]Okay.
[22:18]The next thing we do is we tell Bundler to install GitHub Pages, which will fetch lots of dependencies, including Jekyll. And so we use the command bundle add GitHub Pages, minus minus group Jekyll plugins. The minus minus group tells Bundler to put a tag on all of these dependencies so that later we can update them all in one go. So we can say later, everything to do with Jekyll, I'd like you to update that by saying bundle update group Jekyll underscore plugins. So we're just tagging them all to say all of these fellas you're about to install, they're related to each other and I shall name them Jekyll underscore plugins.
[23:11]Future me thanks you for that one.
[23:13]Oh, future me as well. And you'll see that do lots of stuff, right? That's going to go fetch lots of different dependencies. And one of them will be a version of Jekyll that goes scrolling by. And when I did it, I saw Jekyll 3.10.0.
[23:32]Okay. So where are all these plugins? I'm looking at my docs folder and I don't see them in there.
[23:41]So they are in Ruby's system folder. Oh. which is hiding somewhere in the root of your Mac, along with Ruby 2 and everything else.
[23:53]Okay, so we've just installed all these Jekyll plugins globally on our Mac. We didn't do this to our local repo.
[24:00]Yeah, so there is one copy of them on your Mac centrally. And every time you use Jekyll, you're going to basically have your gem file that says, I would like you to turn on the imaginary toggle next to that plugin that happens to exist on the system. So they exist on the system in an off state, unless you're in a folder with a gem file that says, I want this.
[24:28]Okay, yeah, I can see in the gem file, it says gem GitHub pages, something like 232 of something, group Jekyll plugins.
[24:38]That's a way of specifying version numbers. So basically, like in your package.json file, there's special syntax for specifying at least version X, at most version Y. I don't remember the exact details of the syntax, but it's a way of specifying the version.
[24:56]Okay, so Webrick says 1.9. I just thought it looked weird because it was 232, but I got you. Jekyll auto-prefixer we're going to be playing with, that's 1.0. Got it. Okay. I'm caught up.
[25:06]Okay, so at this point in time, Jekyll now exists on your system, and the docs folder has been told it should use Jekyll in its Ruby environment because it's in that gem file. So as long as you're in that folder, Jekyll is now installed.
[25:30]Got you. Now I get it. Okay.
[25:32]Okay, so that's the point in time. So it's step two point at the very end.
[25:36]I wasn't able to see the version of Jekyll when I scrolled back. It was way too much stuff. So I just did Jekyll minus minus version and I'm on 3.10.0 as well.
[25:46]Okay, so they haven't changed. Great. Okay, so now we're going to make a very, very, very, very basic my first site. It's going to be the world's least interesting website ever, but it's going to prove all of our pieces are connected together. And so now, okay, so up until this point, we have been getting our Ruby environment ready and getting Jekyll installed. From here forward, Jekyll is ready to go on our system, and our system is now behaving in the same way that GitHub Pages will. So for now, until the end of this series, we're just talking Jekyll.
[26:24]
Testing Jekyll Locally
[26:24]Right so this is our mental line draw here so in jekyll's world the file that tells jekyll how to treat a specific folder is underscore config dot yml and so our folder is the docs folder so we save underscore config dot yml into our docs folder and that is the configuration file for our specific Jekyll site. And that file is going to grow, but to have something to start, we're going to put one variable in there, which is basically one entry in a dictionary. The entry is title, and the highly imaginative value is PBS177 test site.
[27:11]Fascinating. We are going to add a single page into our amazing web page. It's going to be the index.html page, but we don't write HTML. We write markdown, which Jekyll converts for us. So we are going to make a file inside the docs folder named index.md. It's going to start with some YAML front matter and then it's going to contain markdown. So the YAML front matter is a dictionary with one key named title. And we're going to give it the value home. And this shows an interesting hierarchy in Jekyll's worldview. Whatever you put in underscore config.yaml is the site-wide version of something. So title in underscore config.yaml is the site's title. Title inside a specific page is the page's title.
[28:12]All right.
[28:14]Okay, so that's the hierarchy it thinks in. And you're going to see that hierarchy a lot. We have a site-wide setting and a more precise setting for a specific page. And very often what you'll find is if you don't specify it on the page, the site's one is used as the default. So it sort of falls back, which can be very convenient. Because if you're the only person writing on a website, you might have a site-wide author and just let it default back to the site-wide author. Don't add an author to every single page because it's the same person as me.
[28:48]Right? Right, right. I want to point out potholes here. BART has very conveniently created versions of these files. So what you can do is you can drag the file or copy the file somehow from the zip file when you download it and drag it in and put it into the folder. Make sure you rename those files. And he says in the instructions to rename them, but this is where I kept falling down. So for example, this site configuration, the config.yaml file, he has it in there as underscore config-1.yml. Nothing works if you leave that .1 in there, it will not work. And it's all through this the first time or maybe first and second time I said, change the name and then after that you're on your own i didn't change them all write it over and over again but don't forget to rename them to exactly what he tells you to do yes
[29:47]And you'll notice there is a underscore config 2.yml because later in the instructions we need to update the file so that's why we have this convention first version next version there hypothetically could have been a third but there isn't they just go right but even.
[30:04]Some of them there's an index.html you had it underscore layout dash index.html or something like that. And that one, you have to make it be index.html.
[30:13]Yes, because it goes inside the layout folder. Yeah. Yeah, basically.
[30:18]Rename everything.
[30:19]Yeah, do what the instructions say, I guess. Yes. Yeah. Okay. Now, we now have the world's simplest Jekyll website. It's two files, a config file and a single markdown file. And that is enough. That is a web page. In order to test it locally, we now need to run Jekyll. And the really cool thing is that by default Jekyll runs in an always on mode where once you start it it builds your website publishes a local web server and it watches the folder so if you make a change and hit save it will update itself in real time show you in the output that it's updated itself show you all the error messages for your silly syntax mistakes you then fix them and you'll see it rebuild and you keep doing that until it's happy.
[31:11]
Running Jekyll and Viewing Changes
[31:07]And then you can refresh your browser. But it means that you don't get your terminal back. As soon as you run bundle exec Jekyll serve, that terminal is serving Jekyll until you kill it with control C. Right. And then you're back to your terminal. Now that's a feature or a bug depending on what it is you're hoping to achieve. But that is how it works. I find that amazingly useful to just start at once and then have it build, build, build, build, build until I'm finished breaking things for the day. And then Control-C, Git, commit, Git, push.
[31:42]Right. I do the same thing in doing JavaScript. Some commands that Helma gave me that do that. And it's awesome. Got real tired of building.
[31:52]Yes, exactly. And the difference is that with Webpack, the default is not to do that. And you have a minus something to make it do that. and Jekyll is the opposite. Its default behavior is to do that. And there is a flag to tell it not to keep doing that, but I don't even remember because I don't want to. Why would you want it? Yeah, exactly. Right. Okay, so one of the nice things is when you run that command, it will tell you the URL that it published your test website to, which by default is going to be htgp.co.com slash slash 127.0.0.1, which is your local PC, on port 4000, which is an unusual port, but it's above port 1024, which means it's an unprivileged port, so it can do that without needing a sudo.
[32:42]And if you go there you will see an amazingly boring web page this is using the default theme so it has a blue title which is clickable and it takes you right back to your home page but you're already on your home page because your home page is your only page So it's a pretty useless default title. And it definitely uses the home page title in the page and in the tab bar. And in my memory, it used the site-wide title as well. But Alison's experience was different. And Alison may just be more observant than me. So it may be using the folder name.
[33:25]I don't know what you mean about it having this in two places, but the tab was definitely not called PBS 177 test site, which you said it would be. It definitely was not. Now, what is the second place you're saying it's going to show?
[33:39]I thought it was the blue bit that you can click on to go right back to where you are. That either says the name of the folder, or it says, well, you're not going to see any of it anymore because you've finished doing all the instructions, so you've replaced the default theme with the custom theme.
[33:56]Right. Hmm. Okay. I definitely didn't see it. I think I saw it. Yeah. Oh, I see what you're saying. I saw it in the navigation on the initial page, but not in the tab. But eventually it showed up in the tab, and we don't know when that happened. So at some point in time, it will be on the tab.
[34:14]It will, because we're going to replace the default theme with a really, really, really basic theme of our own. And I know what my theme does because I wrote it. And I thought I was doing what the default theme did, but it's possible I'm misremembering and I can't go back in time. Or I didn't have time to go back in time. Yeah, and we're not going to use the default theme because it's icky. So don't feel all that pushed.
[34:39]
Preparing for GitHub Deployment
[34:40]Okay so you are now ready to commit and push this up to github so we can make sure this works on the real internet but before we do we need to tweak our git ignore file a tiny bit while the default from github is perfect for when you're using only github pages on the internet when you've done stuff locally you need to give it a little tweak so because we're running in dual mode, github's default is imperfect so we need to add a file to our gitignore file which is our gemfile.lock.
[35:16]What do you mean by dual mode oh that we're running it locally and in github pages okay and gemfile.lock was auto created by gemfile somewhere okay by bundler it's just like Oh, okay. So it's just like we had a package.json lock.whatever. Okay.
[35:34]Yeah, exactly. So you can either edit it manually, use your GUI, or I give you a terminal command to just shove the right line into the very end of your gitignore file, which is probably the easiest thing to do.
[35:48]All righty.
[35:49]So once you've ignored that lock file, then you're ready to commit everything and push.
[35:58]Oh, you said in the show notes, if you forgot to tell GitHub to use the standard ignore file for Jekyll, you also need to add docs slash underscore site to your ignore file.
[36:10]Correct. Sorry, yes, I didn't mean to say that. Now, I'm hoping people did follow our instructions and did choose the right ignore file, because it just makes life easier. Okay, so now it's back. Your code is sitting in GitHub. So now we go into GitHub, we go into the settings, We go to the pages page in the settings and we enable it again, just like last time. We leave the source at deploy from branch, which is its default. We choose main as the branch to deploy from. And when it asks us for a folder, we say forward slash docs and we hit save.
[36:47]Can I make one complaint about GitHub? If your window is too narrow, the word settings is nowhere on that page. Yeah. It disappears into a three-dot menu on the right-hand side. But I remember, I can't tell you how many times I've sat there going, I know Settings is on this page. Where did it go? And I'm like, okay, I'll do Command-F and search for it, and it's not there. It disappears on you. So just widen your window a little bit or look for the three-dot menu.
[37:15]Yes, because it's the rightmost item on the menu, or if not the very rightmost, it's awfully far in that direction.
[37:22]Yep, it's the last one. So sometimes it's the only thing hidden. Like it stops at insights why would i want insights i want what
[37:30]Settings settings give me settings mind you that's the kind of thing you want once when you set up your stuff and then you never want it again i suppose i seem.
[37:37]To be in there a lot
[37:38]Me too okay so as soon as you hit save github actions went off and did its thing so depending on how quick you are when you navigate to actions you'll either see a green tick box or a yellow i'm busy click on the label just like we did last time you'll see the full status of the build and importantly in the publish brick it will have a link for you to click on which takes you to your live version of the website it's.
[38:08]Now called publish it's called deploy
[38:09]Yes it is thank you okay, Yeah, I don't.
[38:14]Know why you keep saying it for quick enough. It takes forever.
[38:19]Minutes. I'm used to slow computers, I guess. Yeah, sorry. Very quick aside, but in work, I went from a 2017 Mac Mini to an M4 Mac Mini. I don't know myself.
[38:36]That's like the Intel Inside thing, right? With the guy in front of... Or no, it was a speaker. Anyway, blown hair back, right?
[38:49]
Building a Basic Jekyll Theme
[38:44]Oh, blown hair back. It's amazing. Everything is so quick. Right. Anyway. OK, so we now have a default Jekyll page which works locally and remotely. If we were to like the default theme, we could leave it at that. I don't. And we don't because I'm just going to speak for all of us here. We have grown up. I don't know if that's the right We've entered the world of web development using Bootstrap as our way of starting our styles, not from scratch. Because I hate empty pages. I'd like someone to do all the common easy work and I'll just make a few tweaks. And so we live in that Bootstrap universe. And so we would like to do the same as we theme our Jekyll site. So we're now going to take our really dumb website and give it enough bootstrap that when we continue this series we are ready to go we are ready to add our content and improve our team in tandem with each other so as we learn how to add different taxonomies we're going to update our theme to be appropriate to those new taxonomies we learn so we're going to do a little bit of jekyll little bit of bootstrap little bit of jekyll little bit of bootstrap and we're going to build ourselves up until we have an amazing page, in theory.
[40:06]So we are going to install Bootstrap. And we're going to do something we haven't done before. So we love Bootstrap, but we have used 10% of it because Bootstrap isn't written in CSS and JavaScript. It's written in a language that compiles to CSS. It's written in SAS. And so what we've been using is the default build of Bootstrap. But actually, Bootstrap was designed to be customizable. So if you download the Bootstrap source code, it has hundreds of variables that you can override with your own values to customize Bootstrap. And then you can say, build me my Bootstrap. And just by changing the variables, you can change loads and loads and loads of stuff. And then as cool as that is, which is already really cool, it's also designed to be extendable. So you can start adding extra things into Bootstrap. So you know the way you have button-primary, button-secondary? You could add button-waffles and have it have a waffly background and just be able to use button-waffles everywhere you can use button-primary and stuff like that. So you can add extra power to Bootstrap.
[41:28]Wow, that's pretty fun. You know, I was going to tell you that this is the first time I've ever downloaded source, I think, of anything. Yeah, absolutely. I always go, no, no, no, no, no, I don't want that one. I want the real one, the one that's like a .dmg or something. Get thee behind me, Satan. I've always run away from that. What I don't understand is we're going to download Bootstrap and mess with it. Doesn't that mean we're forever on that version of Bootstrap?
[41:58]
Customizing Bootstrap in Jekyll
[41:59]Ah, so because Bootstrap is designed to be extensible, as we update Bootstrap, our customizations can stay. So we'll be able to fetch from source. Basically, our customizations are going to sit beside what we download from Bootstrap. So we can re-download from Bootstrap to get a newer version, and our customizations are still sitting next to it. So they'll now apply to Bootstrap 5.1, Bootstrap 5.2, Bootstrap 5.3. We can keep updating bootstrap at our pace and our customizations will reapply themselves to the newer bootstrap and it's designed not to break when.
[42:39]We get into the details i'm going to ask you that again
[42:42]Good please do actually especially in worked example two because that is absolutely where i get to prove it to you and where i can show you the dividing line okay right so So Bootstrap is written in this language that becomes CSS. So it's called a CSS preprocessor because you process something and the output is CSS. So if you write C code, the output can be a .app file. Well, in this case, we're going to write sass and the output is .css. And it just adds extra superpowers to CSS. So the syntax is like CSS, but cooler.
[43:29]And I looked up what Sass stood for again. Syntactically awesome style sheet.
[43:37]Oh, I didn't know that. That's brilliant. That's Sass. Yeah. They have a sense of humor. I love their icon with its sparkliness. There's something about the project I like.
[43:49]Okay.
[43:52]Now, so we need to download the source. And what do I say here in the show? So because Jekyll's default theme uses the same class names as Bootstrap, we have to throw the entire default theme away. We can't just add Bootstrap to the default theme because they will have an awful fight with each other. They do not work together. so that's why we're just going to stop using the default theme we're never going to touch it again and we're going to start with our own pure theme it's going to be really dumb at first how.
[44:30]Do i see the theme we have right now where
[44:33]Is it well so right now over in jekyll it is deep inside jekyll so one of the dependencies is a theme called minami okay it's one of the dependencies it's not in my little folder.
[44:45]Yet of things we've done Okay, we can't see it.
[44:48]No, we can't see it. We can make Jekyll tell us where it is on our system, but we don't see it.
[44:54]Don't worry, you're pretty little head about it.
[44:56]Yeah, we're also never going to use it again. So, very brief visit in our story. Right, so Jekyll has basic SaaS support built in, out of the box, but Bootstrap isn't basic SaaS. Bootstrap is quite advanced SaaS. So we need an optional extra. It already exists for Jekyll, but it's not part of the default Jekyll install because it's an advanced feature. So we're going to use the bundler to add it to our gem file. And we're going to also say, label this one as being a Jekyll plugin. So when we go to update things later, that one gets updated with all the rest. So we're going to say bundle add Jekyll-autoprefixer minus minus group Jekyll underscore plugins.
[45:47]
Finalizing the Theme for Deployment
[45:47]Okay, so this is about browser-specific quirks.
[45:51]Yes. So Bootstrap hides from you the fact that Edge has some quirks that aren't present in Safari. So instead of you having to write all of that into your code, Bootstrap does it for you. Only Bootstrap is an open-source project, so it didn't reinvent the wheel. It uses another open-source project called AutoPrefixer, to handle the weirdness of the different browsers. And so we're just saying, come along for the ride, auto-prefixer. And we'd like the version designed to work with Jekyll so that we don't have to worry our pretty heads about it.
[46:31]And for some reason, they start using the word vendor. So a browser is a vendor.
[46:39]Yeah, I guess so.
[46:41]Well, we're going to need to know that later.
[46:44]Yeah, I'm not sure why they chose the word vendor, but they did. And that causes us a teeny inconvenience. It's an easy inconvenience to work around, only it took me an hour of banging my head off the keyboard to figure out why it wasn't working when I published at the GitHub, because as we'll come to, why? Okay.
[47:01]That frustration may not be. I didn't catch, by the time we got to vendor, I'd forgotten about this browser-specific quirk thing. And so vendor and browser, same, same, same.
[47:10]Correct.
[47:11]Okay.
[47:12]Now, as of now, and this is still true for you, so I guess you can update February to March because it's still true today. There is a quirk in the latest version of AutoPrefixer that it won't allow you to install the latest version of its dependency named exec.js. You need to tell Bundler, I want an older version of exec.js, version 2.7, or AutoPrefixer will break. This is just a known issue. It's listed on their webpage, says, do this, and it won't break. So I did this, and it didn't break.
[47:47]Whose webpage are you on by this time? Are you on GitHub? Are you on Jekyll? Are you on Bundler? You're Gem Ruby?
[47:54]Do you know, I genuinely don't, no, I started off on, I'll tell you where I was. I was on Stack Overflow, because I got an error, and I pasted the error into my search engine and it went there's an answer for you over here and i went thank you very much okay and that linked me to auto prefixers doc which said we have a known bug here's the workaround okay.
[48:19]So it's auto prefixer who has this bug got it
[48:21]Correct anyway bundle add exec js minus v 2.7 and that makes bundler fetch exactly version 2.7 and.
[48:31]Use but you're if you're here in 2027 you may not have to do this
[48:35]Correct which is why i just have the note of the date because there will likely be a pull request from someone five years from now who's following along going by the way bart that's not true anymore it's like thank you very much yes.
[48:49]We appreciate you future whoever you are
[48:53]Yeah we currently have a listener going back through taming the terminal finding our typos from five years ago it's great it's fantastic yeah, Right, so with all of that done, we are now ready to make sure we have our configuration updated to handle this fancy pants bootstrap stuff. So we need to add a few extra settings into our config.yml file. So you'll find a complete copy of the updated file as underscore config-2.yml.
[49:25]I have my hand up, because where did we install Bootstrap?
[49:30]Sorry, we haven't. We're still getting ready. Yeah, we haven't done that.
[49:34]Okay. Sorry.
[49:36]Yeah, my apologies. We're laying the foundation.
[49:39]Is what we're doing. Right. Okay, so this is the config.yaml file, and this is where you're going to tell it that we have this plugin Jekyll auto-prefixer, right?
[49:52]Exactly. So the first thing we have to do is tell Jekyll that it has a plugin now called Jekyll-Autoprefixer, and then we add a dictionary to tell Autoprefixer what we wanted to do. And what we're basically doing is saying, how far back in time do you need to deal with all the known quirks? And the answer is, last four versions by default, with the exception of Safari, where we're only going back two, because with their versioning number, if you go back more than two, insanity because so why.
[50:24]Is it Safari greater than 2
[50:27]You think it'd be what means that we want all Safari, my understanding is that it means that how far back do you want to go we want to go back 1 and we want to go back up to 2 maybe it's like 1.
[50:41]Maybe it's like an arrow that it's not greater than 2
[50:46]All I know is that these version numbers are the ones that bootstrap support because bootstrap 5 only goes so far back in time like bootstrap 5 has a dependency that we don't do ie for example bootstrap just yeah doesn't do internet explorer anymore thank goodness and so basically the bootstrap docs told me this is what bootstrap wants yeah yeah right now we can install bootstrap and we have to download the source like you say not something we're used to doing. And then we're going to have to find the right pieces of the source code and put them in the right place, which is my opportunity and or requirement to tell you about some folders that are very important in the Jekyll universe. So this is now Jekyll universe.
[51:35]
Managing Assets and Dependencies
[51:35]So the first thing I'm going to tell you is a convention. So you could name the assets folder waffles and it would still work but every document you find on the Jekyll page and every answer you find on Stack Overflow will assume you've done the convention and you're going to spend all of your time fighting the convention so don't do that I.
[52:01]Promise I'll be good
[52:03]Yes. So by convention, all of the non-HTML your theme means is referred to as an asset. That's just the jargon of web design. So your theme is going to have some style sheets, their assets. It's going to have some JavaScript, their assets. It might have some icons. It might have some logos, their assets too. And so all of those get collected into a folder we name assets. And by secondary convention to stop chaos it's normal to create subfolders in there to keep things nicely organized so assets slash js for javascript and assets slash css for your css files and this is where we have an interesting thing to understand so jekyll is going to take our docs folder and translate the markdown files into html files and every sas file into a css file so we're going to write assets forward slash css forward slash some name dot s css so super css or sas css whatever you want to think that stands for and jekyll is going to convert that same file to have the same name, but the .css file ending, because it's going to turn it from SAS into CSS.
[53:28]So when we're writing our HTML, when we want to refer to style.scss, we're going to say in the HTML, style.css. But that's sensible, but not obvious.
[53:44]Yeah, wouldn't have jumped out to me. I would have probably changed that as a typo in the show notes.
[53:49]Exactly, because it's not obvious, but it's not silly.
[53:52]Okay, so let me say it one more time. So we're going to have these files that'll be blah.waffles.scss, and that's the supercharged CSS file. But Jekyll is going to go through and it's going to turn that into CSS files, just like it's going to take our markdown and turn it into HTML.
[54:11]Bing, bing, bing.
[54:12]Okay. Perfect. Got it. Cemented.
[54:14]Now, yes. So one of the superpowers of SAS files is that you can import other people's CSS into your CSS using an add import directive. And that's how we're going to pull Bootstrap in. We're just going to say add import Bootstrap. And the question then is, where do those imports come from? because those imports aren't ever a final output. They're something used while turning our file into CSS. So they're like a hidden dependency. So they don't go in the assets folder. They get put aside. So your SAS helper files don't go in the assets folder. They go in a special folder that never gets visible in the output website called underscore sass. And this might give you a hint of a pattern we're going to explain in detail next time. But everything that starts with an underscore is only used to create the site. It's not in the final output. So underscore config doesn't end up in your final output. It's just a configuration file. Underscore sass doesn't end up in your output. It's helper files to help create the .css. Thank you.
[55:33]Okay, but underscore site is where the index.html is, and that is the site. So underscore doesn't mean...
[55:40]No, no, underscore site isn't in your source code. Underscore site is the cached copy of your website that you're going to upload to your web server.
[55:50]Yeah, but you just said that anything starting with underscore doesn't end up in the website, and underscore site does.
[55:57]But you didn't write underscore site.
[56:00]I didn't say I did.
[56:02]Yeah. Okay, everything starts with an underscore is special. If you wrote it, it's not going into underscore site.
[56:12]Oh, okay. Okay, that makes sense. Got it. Gotcha. Okay, so assets is where I'm messing around. I'm writing my JavaScript, I'm writing my CSS, and that doesn't have an underscore on it.
[56:23]Bing, bing, bing, which means it ends up in the output. and its helper files are in the underscore sas folder okay so what does that mean for us well bootstrap contains some c some sas files and some javascript files so the sas files go into the underscore sas folder and the javascript files go into the asset slash js folder so when we, look into that zip file we downloaded from bootstrap we extract it you're going to do two things so you're going to first thing you're going to do is make a new empty folder called underscore sas forward slash bootstrap and then you're going to take the content of the scss folder that you downloaded from bootstrap and put it in that bootstrap folder you just made and.
[57:19]I would like to emphasize the word
[57:21]Contents contents because.
[57:23]I made underscore sass and inside that i made bootstrap and inside it i put that
[57:29]Another bootstrap.
[57:32]No, no, it wasn't Bootstrap. It was a folder that you called out.
[57:35]It was called SCSS.
[57:37]Yeah. So you could
[57:38]Have worked around that by saying at import forward slash Bootstrap forward slash SCSS forward slash Bootstrap, and then it would have worked.
[57:47]Or it could have read the instructions properly.
[57:50]Yeah, that would have been easier. The second thing you're going to do is make a new folder called docs assets JS, and you're going to copy two files from Bootstrap's dist slash js folder. You're going to copy bootstrap.bundle.min.js and bootstrap.bundle.min.js.map. And that's the JavaScript.
[58:14]Okay, holding my hand up. Holding my hand up. This is where I'm saying, we downloaded the source code for Bootstrap and then we reach in and we just grab this folder of stuff for Sass and we just go get this little bit of these, just these two little files for JavaScript and we leave all the other stuff over there that hasn't been compiled and you're telling me that we'll be able to update Bootstrap and those two, these few files are going to, it's all going to work.
[58:39]
Adding Interactive Elements with Bootstrap
[58:40]Yes. Okay. What we've done is we've accepted the pre-compiled versions of the JavaScript because we're not going to mess with that. Pre-compiled. And the un-pre-compiled version, so the bundle file, so bootstrap.bundle.min.js is actually built. That is the built JavaScript.
[59:01]Oh.
[59:03]But we're not going to take the built CSS. So we're having our cake and eating it. We don't want to rebuild the JavaScript. That's fine. We do want to rebuild the CSS. So that's why there's a difference.
[59:19]Okay, but there were a lot more files in that folder than just the two, the bootstrap.bundle.min.js and .js.map. There were lots more JavaScript files.
[59:28]So that entire disk folder is full of different builds. So you have a minimized build, you have a build in lots of little pieces where you can have different... If you only want a subset of Bootstrap, you don't have to download it all. So inside that dist folder, you could grab specific bootstrap.toast and bootstrap.popup and bootstrap.carousel. So you can pick and choose your Bootstrap pieces if you want to have the world's most efficient website. Or you can be lazy and say bootstrap.bundle. Give me it all. Just give me all of it.
[1:00:00]I just feel like we went in and we took one kidney and the left pinky finger.
[1:00:07]Yeah weird if you watch Star Trek Voyager there's a species that go around stealing organs that's kind of what we're doing here we're taking the parts of Bootstrap we want yeah yeah exactly, yes can't remember the name of that species anyway I'm watching it right now on Mission Log wasn't the one with.
[1:00:25]The phage was it
[1:00:27]Was the ones with the phage they were very ugly but anyway yeah okay okay with all that said, this is now the point where I bit myself in my own backside and caused myself a lot of frustration because, normally in Ruby universe the folder vendor is one of those folders you never ever ever commit to git like in npm world the folder packages never goes into your git because that's like a a place where dependencies get installed. However, Bootstrap isn't Ruby. So Bootstrap did use the folder vendor, But our default git ignore file tells git to ignore every folder named vendor everywhere in our repository. So we need to add one exception, just one specific exception. This one folder named vendor is not to be ignored. And did you look up which.
[1:01:31]Bloody show notes? I did, CBS 120.
[1:01:33]Oh, thank goodness. Thank you, Alison. I just realized now, as I was about to say the words, that I forgot to check what installment it was, but we covered this in PBS when we did Git. So the way you add exceptions is that you add them to the ignore file after the directive that would normally ignore them. And you basically say, ignore all vendor files, except. And the way you say except is to start your line with an exclamation point. So we say exclamation point forward slash docs forward slash underscore sass forward slash bootstrap forward slash vendor forward slash which means ignore the specific folder and all of its content sorry ignore ignoring so don't ignore don't ignore is how you say that in English don't ignore that one vendor folder but do continue to ignore the others well.
[1:02:31]The exclamation point means not so that makes sense right not this one
[1:02:35]Exactly ignore.
[1:02:36]Everything not this one
[1:02:38]Exactly.
[1:02:39]Yes. Okay.
[1:02:41]And again, there's a terminal command to just shove that into the back of your file. So that's the easiest thing to do. Now, inside our underscore sass folder is a copy of Bootstrap's source files. That underscore scss folder is not going to be in our final output unless we actually at import it. Because it's just a utility file available for us to import into an actual css file that we're going to include in our HTML.
[1:03:13]Hang on, hang on, back up. What is going to be? Start that all over again. I'm lost. Okay.
[1:03:20]So we now have Bootstrap's source files for the CSS. But unless we make a CSS file that includes that Bootstrap source, we don't actually have a usable version of Bootstrap.
[1:03:35]Wait, we've got the SCSS files from Bootstrap. And unless we create an scss file we don't have them right
[1:03:46]Okay so everything in assets gets translated to real css and put into our underscore sites folder right everything in underscore sass gets ignored unless we explicitly import it we have to import it somewhere.
[1:04:03]Nothing to do with git ignore we're just saying it just it doesn't get talked to it you gotta tell it go Look in this folder, because there's some really cool stuff over there.
[1:04:12]Correct. So we are going to make a starter style sheet. And our starting point is, just give me all of Bootstrap. Now, we're going to add more to this file over time. We're going to start customizing Bootstrap in this file. But our starting point is, give me Bootstrap. And so all we're going to do for today is that starting, or for right now, this moment, is that starting point. So now I'm going to tell you something Jekyll specific. The way Jekyll's SAS processing works is its rule is I will compile every file with the extension SCSS that has front matter. Hmm i will ignore every other file that isn't that that won't get run through the sas processor so in order to be converted it has to meet that rule end in that file name and have front matter now we don't actually need to tell it anything so our front matter is empty it's three dashes followed by three dashes it is empty front matter okay.
[1:05:25]And then you tell it add import bootstrap bootstrap
[1:05:28]Yes for some reason if you okay what that's saying is my style sheet is going to start by taking all of bootstrap so if you look in your underscore site folder and you open style.css you're going to see all the bootstrap code.
[1:05:48]No under sass
[1:05:50]No no in the site the underscore site folder the output of creating your jekyll site is going to have pulled all of Bootstrap into a file named assets forward slash CSS forward slash style dot CSS.
[1:06:09]Yes.
[1:06:11]So that's what the ad import did.
[1:06:13]I'm just asking, why is it Bootstrap, Bootstrap? Why is it twice?
[1:06:21]
Introduction to Jekyll's Liquid Templating
[1:06:16]Ah, okay. So if you open the underscore SAS folder, there's a folder named Bootstrap. And if you open that folder, there's a file named bootstrap.scss.
[1:06:31]Yes, he's right. Okay, I had to go past all the underscores. Okay, let me back you up to, shoot, I had another question. Oh, you said that Jekyll would ignore anything that didn't have, any scss file that didn't have underscores on it. None of the bootstrap scss files have front-women.
[1:06:52]Because they are in the SAS folder They are there for us to talk to They are not in our assets folder So they are not being compiled They're being imported.
[1:07:04]Okay, okay, got you
[1:07:07]Yeah, it's a subtle difference, but that is how it works.
[1:07:11]Okay.
[1:07:12]Right. So we are now going to make our own really straightforward theme. Amazingly straightforward theme. And for today, I'm going to do something I am fundamentally not comfortable doing. I'm going to ask you to treat some of the stuff in this file as magic sauce. On the promise that I will demystify all of it shortly. But for today, I'm not going to teach you the liquid templating language because we've been going for a while and that's too much. So you're going to make a file named default.html and it needs to be placed in a folder named underscore layouts because underscore layouts is where Jekyll expects its theme files. And you can have many layouts in your theme but there has to be a default layout and for today we're going to have exactly one layout a default layout and for the most part it's an html file so it's actually an html5 html file and it has all of our usual bootstrap stuff the meta car set utf8 because bootstrap gets very cranky if you don't use utf8 the meta name equals viewport because bootstraps, various styles don't work if you don't tell it what to do on mobile screens.
[1:08:37]And then we're going to give the page a title. And we're going to ask Jekyll to give us the page's title, then a vertical pipe symbol, and then the site's title. So that's going to become Home, Pipe, whatever we called our site, PBS 177 test site. So that's going to get inserted. It's a bit like Mustache. It's very like Mustache.
[1:09:02]Very Mustache-y.
[1:09:04]Then we're going to import our style sheet which we are going to take from assets forward slash css forward slash style dot css, then we're going to start our body we're going to put a container so that bootstrap does it has something to wrap everything with and then there's a placeholder that says my content from the markdown file goes here that's what curly bracket curly bracket content close curly bracket curly bracket. So all of that markdown gets turned to HTML, and that HTML gets shoved where that placeholder is. And then we have a script tag that goes and fetches bootstraps JavaScript, shoves that in the bottom of the body, and then finishes your HTML page. So our markdown files end up as HTML files with this structure. Looks good yeah so let's prove that that's all working if you don't still have it running bundle exec jekyll serve and now when you refresh your browser what you will see, is the same basic content because we haven't touched our markdown file but instead of it having that default theme which has the blue clickable header that just takes you back to itself because you only have one page you have bootstraps nice default font and you're going to see the title of the page and if you look up at the tab bar it will say the title of the page vertical pipe symbol the title of the website.
[1:10:33]Right, right.
[1:10:35]
Finalizing the Theme and Testing
[1:10:36]Not very exciting, but there we are. We have the world's most primitive theme, and it's using Bootstrap. Let us now prove that our Bootstrap really is fully ready to go. So Bootstrap's JavaScript is, in theory, there for us, so we can make things that are clickable. And Bootstrap's SAS files are there. So for the first time ever, we can customize Bootstrap. So we're going to verify both of those two things. So the first thing we want to do is verify that we can customize Bootstrap by going back into our SCSS file that started by only importing Bootstrap. Before we import Bootstrap is where you override Bootstrap's variables. So Bootstrap's documentation lists all of its possible variables and all the possible values. And anyone you want to customize you set your values and then you add import bootstrap and then as bootstrap loads it uses your values instead of its own defaults so.
[1:11:40]Is this where i can make button dash primary be waffles
[1:11:42]No that happens later so that's extending bootstrap right so.
[1:11:48]You okay customize
[1:11:50]Bootstrap before you import bootstrap and you extend bootstrap after you import bootstrap. So if you wanted to add waffles, you do that after the add import.
[1:12:00]No, I'm saying if I wanted to replace primary with waffles.
[1:12:04]No, no, sorry. In my example, it's you add.
[1:12:07]Oh, yeah, yours was adding. Yeah, okay. Okay. Okay, good. I'm glad I asked that because those are two different things. So you override existing variables before you import Bootstrap. You say, before you even talk to me, I've decided I want this this way. So don't you overwrite this. And then afterwards you say, hey, I want to add all this other cool stuff.
[1:12:27]Bing, bing, bing. So for today, just to prove we have everything working, we're just going to override two variables. They're not useful variables, but they do prove that our stuff is working. So we're going to change the body background to light sky blue and the body color, which is the default text color, to midnight blue. And so that would be obvious that we've done something. So we add those two dollar. So basically in SAS variables start with a dollar symbol. So we're defining a variable named body dash bg, giving it the value light sky blue, defining a variable body color, midnight blue, and then at import bootstrap. And then as Bootstrap comes in, it uses those colors instead of its defaults of white and black.
[1:13:10]Oh, look, it's blue.
[1:13:12]It's blue. So to prove that our JavaScript is working, we need to add some sort of interactive clickable Bootstrap doodad. And I chose to add a dismissible alert. So it'll be an alert with a close button. And if the JavaScript is working, when you click the close button, the alert will close. So we're going to edit our theme to add a silly alert that serves no useful purpose. It's going to be a div class alert, alert info, alert dismissible, fade show. And it's going to have the role of alert. We're going to say click my close button to prove that Bootstrap JavaScript is working. Then we're going to add a button.
[1:13:50]This is in the HTML now we're doing this.
[1:13:53]This is in the HTML. So this is in our theme. So this is going to be wrapped around our markdown.
[1:14:01]So I've got to start thinking of default.html as the theme. I think of that as the content.
[1:14:08]Now the markdown is the content, right? So once your theme is set up and running, all you're doing is writing in markdown.
[1:14:15]Yeah.
[1:14:16]So basically we inject into the top of our theme. We just shove in that dismissible alert. And then we build it again and we load our page. And now we have an alert with an X button. And when we click the X, Bootstrap's JavaScript makes it go away.
[1:14:32]So it is a little bit weird that you put content into the theme, but it's for this exercise.
[1:14:39]Yeah, and it's like in a real world, you'd have like a collapsible info pane or something. Like you do something sensible, right? I'm just like, I need something to prove this works.
[1:14:51]This is perfect.
[1:14:52]Yeah. And again, once it's working locally, git commit, git push, wait for GitHub pages to build. And what you should see on the real internet is identical. That is literally the whole point of what we've done today.
[1:15:07]If when you push to GitHub and you watch the actions go, if it fails over in a heap and spits all kinds of garbage on screen and tells you that it's not working, it might just be lying. Because I had this happen. And Bart was out on his bike. I was stalking him on Find Friends like I like to do. And I could see he was coming into home. And I thought, you know what, let me just do the rest of the exercise so that I can get finished. And then I'll push all of the changes at the end. And when I pushed all of the changes at the end, it was fine. There wasn't anything wrong. It was telling me that there was a value of nil that couldn't be turned into an integer that was part of a file that didn't have anything like that in it. It just made no sense. so just just push it again
[1:15:52]Yeah sometimes you just add a space to a file so that it sees a difference git push and it goes oh i think i will we have that sometimes on real pbs right where it freaks both of us out it's like oh my god the build failed i'm gonna
[1:16:09]
Ready for Content and Future Enhancements
[1:16:07]change nothing and push it again oh the build's fine i.
[1:16:10]Think i'm gonna make a uh text expander snippet for a git commit message that says fix colon tickle git or github pages
[1:16:18]Yeah that is kind of what you're doing right so just do it again just do it again yeah right so what we've done today is we've laid the foundation so that we can run the same jekyll site locally to debug and on github pages to publish to the internet and so from now on our modus operandi is going to be make changes test until they stop breaking git commit git push then they'll be on the internet.
[1:16:50]Right. So if I want to do this on another Mac, I would need to do the Ruby install stuff and gem stuff and bundle stuff, and then just pull and it should be able to work.
[1:17:05]Yes.
[1:17:06]Okay.
[1:17:07]So once you pull, you probably have to do, there's probably a bundle init command to say, you see that file you just pulled down? because you're going to pull down a complete gem file, right? Your gem file that you get from the git pull is going to have everything you need. So you shouldn't have to say gem or bundle add. You should just be able to tell bundle to take that existing file and pick up where it left off. And I forgot to look up the command to do that. That is, I will put a pin in that because that is something we need to learn for new Macs. Because you're right, if I have it working on my laptop, Why don't I want it on my desktop?
[1:17:48]I have a piece of paper here with questions I was going to ask you. The number one question is, what if we get a new Mac?
[1:17:55]Yeah. So you know the way with NPM, we use the NPM CI command to just take whatever Git gave it and do that again. There's an equivalent bundle command. I just don't have it off the top of my tongue.
[1:18:06]Okay. But it'll be in the show notes before people see it.
[1:18:09]We'll be good to go. No, I think we'll actually cover it explicitly in the next installment. In the next one. Because we're going to have to explain it, right? We should explain it. So I think we'll do it next time.
[1:18:17]Okay, great, great. Well, I know this took a long time, but this literally took half the time it took me to do it by myself. So going through it with you is great, and I'm sure everybody will do smarter than I did. Yes. I learned a lot mucking it up, though.
[1:18:34]That is the best way to figure it out. And that's basically what I spent the last two weeks of January doing, is getting this wrong many times, and then each time tweaking the show notes to get out the wrong instructions and replace them with correct instructions.
[1:18:47]I tripped up many times. So we are now ready to start adding content. And as we add content, we need to add features to our theme to make use of the content we're adding. So at the moment, there's no nav bar because we have one page. When we add more than one page, we're going to need a navbar. A navbar is going to teach us how to write a for loop to iterate through all of our different pages so that as we create more files, the navbar updates automatically. Then we've got to learn how to add blog posts, which means we're going to have to be better at our for loops because we're going to have a list of blog posts in reverse chronological order. So we're going to need a for loop to add those into our theme. You're going to need to have next and previous buttons in our theme. So our theme is going to have to keep getting cleverer right a blog post has a date a page doesn't have a date it's eternal content so our theme needs to be clever enough to say that if i'm showing you a blog post i should put a date here whatever else that's blog post only so we're going to grow the two piece by piece so we're going to learn a little bit more theme a little bit more jekyll to add new content types a little bit more theme a little bit more jekyll a little bit more theme a little bit more jekyll and for one or two installments i am going to occasionally have to ask you to accept some temporary magic sauce but i want to minimize the amount of magic sauce and i absolutely guarantee you that we will demystify it all.
[1:20:15]We just may need a few more pieces before we're ready to demystify it so i'm going to ask you in advance to bear with me a little bit we're going to do something i don't like doing but i genuinely can't see another way to do it.
[1:20:25]I uh trust you on that because you very rarely do it so i think it's I think it's fair. We will allow it.
[1:20:32]Yay. Right. Well, with that, folks, I wish you all lots and lots of happy computing.
[1:20:41]If you learn as much from Bart each week as I do, I'd like you to go over to lets-talk.ie and press one of the buttons over there to help support him. He does 98% of the work here. I'm just the stooge that listens to him and asks the dumb questions. If you go over to let's-talk.ie, you can support him on Patreon, you can donate via PayPal, or you can use one of his referral links. I really hope you'll go over and help him out. In the meantime, you can contact me at Podfeet or check out all of the shows we do over there over at podfeet.com. Thanks for listening.
[1:21:17]Music