WIP: PBS 177 wording tweaks

docs/_pbs/pbs177.md

@@ -5,9 +5,13 @@ miniseries: GitHub Pages
 creators: [bart, allison]
 date: 2025-02-05
 ---
-Having learned how to create our own GitHub Actions workflow to publish a website using a custom build system, Webpack in our case, we're not moving on other use GitHub's default workflow to publish a site with the Jekyll Static Site Generator.
+In [the previous instalment](./pbs176) we learned how to use GitHub Actions to publish a web app using a custom build system, Webpack to be precise. We're now moving on to solving a completely different problem — using GitHub Pages with Jekyll as a content management system. This is GitHub Pages' default mode of operation, so we won't need to build our own custom GitHub Actions this time, instead, we'll be relying on the default GitHub Pages workflow provided by GitHub.
 
-We're going to do it in such a way that we can test our site locally before sending it to GitHub, and, so we are bundling Bootstrap in a customisable way.
+In the previous instalment we made a point of using GitHub Pages in such a way that we could test our apps locally before pushing the tested code to GitHub and triggering an automated deployment to the internet. This kind of local testing removed a lot of friction from the development process, greatly speeding up debugging in particular. Hence, we'll focus on using GitHub Pages and Jekyll in such as way as to facilitate the same kind of local testing. This approach complicates the initial setup of our projects a little, but that extra work up-front more than pays for itself over the lifetime of any site developed in this way!
+
+Finally, rather than building the theme for our sites completely from scratch, we'll use Bootstrap as our scaffold, and built on top of the solid foundation it provides. Because Jekyll supports Sass out-of-the-box, and Bootstrap uses Sass for customisation, this is the perfect opportunity to learn how to customise Bootstrap to customise it's default behaviours and add new bespoke features as well.
+
+In this instalment we're going to start by laying a solid foundation for our work with Jekyll. We'll learn how to start a Jekyll project on our local PCS, test and run it, and then publish it to the internet with GitHub Pages. We'll start our Jekyll project with the simplest possible HTML 5 theme, and then add Bootstrap in such a way that it is ready to be customised later in the series.
 
 ## Matching Podcast Episode
 
@@ -19,15 +23,15 @@ TO DO
 
 ## Some Important Context
 
-It's important to note that that if we you don't want the ability to test your GutHub Pages site locally you can skip most of this instalment and simply enable GitHub Pages to start serving your `docs` folder just like we did in the first of the two worked examples in [the previous instalment](./pbs176). At that point you can create a standard Jekyll directory structure and start building your site.
+It's important to note that if we you don't want the ability to test your GutHub Pages site locally you can skip much of this instalment and simply enable GitHub Pages to start serving your `docs` folder just like we did in the first of the two worked examples in [the previous instalment](./pbs176). At that point you can create a standard Jekyll directory structure and just start building your site.
 
-However, there's a very good reason not to take that easy route if you plan to use Jekyll as a full content management system — if you do your only means other than testing your site will be to actually publish it on the internet, and you'll need to do a full commit to `main` for each change you want to test. This is inordinately tedious for debugging work!
+However, there's a very good reason not to take that easy route if you plan to use Jekyll as a full content management system — if you do your only means of testing your site will be to actually publish it to the internet by doing a full commit to `main` for each and every change you want to test. This is inordinately tedious for debugging work!
 
 The extra work described in this instalment results in a Jekyll site that is **both** compatible with GitHub Pages, and, with a local install of Jekyll.
 
 I mentioned in the introductory instalment that GitHub Pages uses a customised version of Jekyll, and that's a vitally important point to understand. Because if its various customisations, you don't install Jekyll directly in your `docs` folder, instead you install a `github-pages` package which lists many dependencies, including the specific version of Jekyll currently supported by GitHub Pages. This is always a somewhat older Jekyll version. As of February 2025 the main Jekyll project is at version `4.3`, but GitHub Pages is using Jekyll version `3.10` .
 
-**This lagging version number is important to keep in mind when reading the [Jekyll documentation](https://jekyllrb.com/docs/)**. Newer features will be annotated with the Jekyll version in which they were first added, some newer features are not available when using Jekyll on GitHub Pages.
+**This lagging version number is important to keep in mind when reading the [Jekyll documentation](https://jekyllrb.com/docs/)**. Newer features will be annotated with the Jekyll version in which they were introduced, so at any time, some of the newer features described in the documentation will not yet be available for use with GitHub Pages.
 
 ## Preparing to Run Jekyll Locally
 
@@ -62,8 +66,7 @@ echo "chruby ruby-3.3.5" >> ~/.zshrc # run 'chruby' to see actual version
 ```
 
 > These instructions assume a modern version of macOS using Zsh, if you're still using Bash edit the commands to append to `~/.bash_profile` instead of `~/.zshrc`!
->
-> {: .notice}
+{: .notice}
 
 With all that done, close and re-open your Terminal to pick up the new Ruby configuration. Verify your are using Ruby 3 now with the command:
 
@@ -166,8 +169,7 @@ bundle exec jekyll serve
 This will render the contents of the `docs` as a website and write the generated files to the folder `docs/_site` and then start a locally running web server on port `4000` with that folder as the source. You'll see the URL for this local server in the output, and by default it will be `http://127.0.0.1:4000`. 
 
 > Note that this command does not exit, but keeps running. You can kill the local server at any time with `ctrl`+`c` or closing the common prompt, but you'll only need to do that when you're finished for the day, because the Jekyll server monitors the file system for changes, and automatically re-builds your site each time you change a file in the the `docs` folder. This make debugging very easy.
->
-> {: .aside}
+{: .aside}
 
 To see the generated site, open the URL in your browser.
 
@@ -180,7 +182,7 @@ Notice that the page title defined in the front matter in `index.md` also appear
 
 The rest of the content of the home page is the rendered markdown from the body of `index.md`.
 
-### Step 5 — Commit & Push the Jekyll Site
+### Step 5 — Commit & Push to GitHub
 
 Before we commit our changes, we need to add two items to the `.gitignore` file:
 
@@ -302,6 +304,10 @@ With this changes made, we can test our site locally with the `bundle exec jekyl
 
 Commit all changed files and push to GitHub. Watch the build action as normal, and then verify that the published site is now successfully changed to using Bootstrap.
 
+### Step 8 — Test Bootstrap
+
+TO DO
+
 ## Final Thoughts
 
 TO DO