From 5b95262f17503943c8c6fd5d4ce32cff1de09c14 Mon Sep 17 00:00:00 2001 From: Allison Sheridan Date: Fri, 31 Jan 2025 17:55:19 -0800 Subject: [PATCH 1/6] Feat: typos and many questions they're probably all softballs! --- docs/_pbs/pbs175.md | 92 ++++++++++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/docs/_pbs/pbs175.md b/docs/_pbs/pbs175.md index 1a0107a..cb5a9e0 100644 --- a/docs/_pbs/pbs175.md +++ b/docs/_pbs/pbs175.md @@ -5,22 +5,22 @@ miniseries: GitHub Pages creators: [bart, allison] date: 2025-02-01 --- -This instalment is the start of a new series-within-a-series focusing on the technology that powers this website, and, that hosts the new JavaScript version of [XKPasswd](https://www.xkpasswd.net) — GitHub Pages. +This instalment is the start of a new series-within-a-series focusing on the technology that powers this website and that hosts the new JavaScript version of [XKPasswd](https://www.xkpasswd.net): GitHub Pages. -GitHub Pages provides a very interesting free web hosting option that inherently provides a full version history to easily recover from any kind of whoopsie. It's also surprisingly versatile and powerful. On one end of the spectrum you can use it to simply host a folder of HTML, CSS & JavaScript files exactly as they are, and on the other end of the spectrum you can build a full content management system with all the taxonomies and content organisation features you would expect from a typical blog or corporate site. The mechanism GitHub Pages uses to achieve this is completely different to that used by the most popular content management system in the world, [Wordpress](https://wordpress.org), but is fundamentally the same as that used by the fashionable new up-and-comer, [Hugo](https://kinsta.com/blog/hugo-static-site/). +GitHub Pages provides a very interesting free web hosting option that inherently provides a full version history to easily recover from any kind of whoopsie. It's also surprisingly versatile and powerful. On one end of the spectrum you can use it to simply host a folder of HTML, CSS & JavaScript files exactly as they are, and on the other end of the spectrum you can build a full content management system with all the taxonomies and content organisation features you would expect from a typical blog or corporate site. The mechanism GitHub Pages uses to achieve this is completely different from that used by the most popular content management system in the world, [WordPress](https://wordpress.org), but is fundamentally the same as that used by the fashionable new up-and-comer, [Hugo](https://kinsta.com/blog/hugo-static-site/). -In this first instalment we'll set the scene, explaining the difference between dynamic content management systems like Wordpress, and static site generators like Github Pages and Hugo. We'll also give a big-picture overview of how GitHub Pages works, and hence, the technologies we'll be exploring over the coming months. +In this first instalment we'll set the scene, explaining the difference between dynamic content management systems (CMS) like WordPress, and static site generators like Github Pages and Hugo. We'll also give a big-picture overview of how GitHub Pages works, and hence, the technologies we'll be exploring over the coming months. ## Matching Podcast Episode TO DO -## What Problems do Content Management Systems Solve? +## What Problems Do CMS Platforms Solve? -Before we get lost in the weeds of the two different architectures for content management systems, let's step back for a moment and describe the problem all these systems set out to solve in their own distinct ways. +Before we get lost in the weeds of the two different architectures for CMS platforms, let's step back for a moment and describe the problem all these systems set out to solve in their own distinct ways. 1. **Separation of content creation from content presentation** - 1. Separation at the **task** level — even if one person is running the entire site, they can easily focus on either designing it, or, creating content, they never have to wear two proverbial *hats* at once + 1. Separation at the **task** level — even if one person is running the entire site, they can easily focus on either designing it or creating content, they never have to wear two proverbial *hats* at once 2. Separation at the **storage** level — regardless of how the data is stored, the content is segregated from the site's design 3. It should be possible to change the content without needing to edit the design, and to change the design without editing the content 2. Content needs to be **organised** into sensible taxonomies, and new content should automatically appear in the correct locations within the site based on the taxonomies the creator applies. Examples of taxonomies include: @@ -29,23 +29,23 @@ Before we get lost in the weeds of the two different architectures for content m 3. Categories 4. Tags 3. Support an **editorial process** — the details will differ from organisation to organisation - 1. Content management systems need to facilitate an organisation's desired process for creation, review, and publishing of content - 2. For personal sites or sites for small organisations the needs here may be very basic — perhaps just a mechanism for marking content as being in draft + 1. Content management systems need to facilitate an organization's desired process for creation, review, and publishing of content + 2. For personal sites or sites for small organisations, the needs here may be very basic — perhaps as simple as a mechanism for marking content as being in draft before publishing ## Two World Views — Dynamic & Static -All content management systems combine content with a theme of some kind to produce the HTML, CSS & JavaScript readers view in their browsers. The two big questions are: +All CMS platforms combine content with a theme of some kind to produce the HTML, CSS & JavaScript behind the reader's view in their browsers. The two big questions are: 1. When does the content get rendered to HTML, CSS & JavaScript? 2. Where is the content stored? -In theory these two questions are not linked, but in reality they almost always are, so we get answers to both questions with just two categories of CMS. +In theory, these two questions are not linked, but in reality, they almost always are, so we get answers to both questions with just two categories of CMS. -### Read-Time Rendering — Dynamic CMSes +### Read-Time Rendering — Dynamic CMS Platforms -More traditional CMSes like Wordpress render pages on-demand, the moment the reader would like to read them. This is done using a server-side language like PHP, and the content is stored in a relational database. +More traditional CMS platforms (like WordPress) render pages on demand the moment the reader would like to read them. This is done using a server-side language like PHP, and the content is stored in a relational database. -When you visit a Wordpress site like Podfeet.com your browser sends a request to Allison's web server which then runs PHP code which reaches back to a web server Allison runs and builds the web page you requested, and returns it to your browser. +When you visit a WordPress site like Podfeet.com, your browser sends a request to Allison's web server which then runs PHP code which reaches back to a web server Allison runs and builds the web page you requested, and returns it to your browser. As you browse Allison's site from page to page, the same process happens again and again. @@ -55,9 +55,9 @@ There is a significant amount of infrastructure needed to power a website like t 1. A Linux or Windows server with a web server like Apache or NGINX and PHP 2. A Database server -3. The Wordpress code +3. The WordPress code -The server has quite a bit of work to do on each page view, so a small number of users can make a lot of work for this infrastructure. Spikes in traffic can easily cause excessive loads on the server, so for even vaguely popular sites an additional layer of infrastructure is needed — a caching server. For this cache to be effective it needs to be tightly integrated with Wordpress so it can know when a particular post has been edited, or a new comment added, so it can invalidate it's cached copy of that page and ask the server for a fresh rendering next time a user asks for it. +The server has quite a bit of work to do on each page view, so a small number of users can make a lot of work for this infrastructure. Spikes in traffic can easily cause excessive loads on the server, so for even vaguely popular sites, an additional layer of infrastructure is needed — a caching server. For this cache to be effective it needs to be tightly integrated with WordPress so it can know when a particular post has been edited, or a new comment added, so it can invalidate its cached copy of that page and ask the server for a fresh rendering next time a user asks for it. Running a dynamic website involves continued bills and at least some amount of maintenance work to keep everything patched and secure. @@ -67,46 +67,54 @@ But you do of course get some advantages: 2. Content can be published at a high rate 3. User interaction like comments is natively supported 4. Authors and editors can use a web interface to manage the content +5. Once things are set up properly, very little technical skill is required to create content +6. There is a vast community of people creating themes and plugins to enhance the things the site can do (especially for WordPress) ### Publication-Time Rendering — Static Site Generators -Static Site Generators like GitHub Pages turn things on their head completely. The entire site is rendered to HTML, CSS & JavaScript when new content is published, and those pre-generated files are copied to a basic web server that serves those same simple HTML files to all visitors. +Static Site Generators (SSG) like GitHub Pages turn things on their head completely. The entire site is rendered to HTML, CSS & JavaScript when new content is published, and those pre-generated files are copied to a basic web server that serves those same simple HTML files to all visitors. -Static Site Generators generally store their content in files on the file system, so there is no database, and hence no need for a database server. The web server doesn't do any rendering, so it's load is minimal, and it doesn't need any server-side languages installed at all. +Static Site Generators generally store their content in files on the file system, so there is no database, and hence no need for a database server. The web server doesn't do any rendering, so its load is minimal, and it doesn't require any server-side languages. -The site generation of the can be done anywhere, even on your own PC, and the generated files can be moved to the server by any file-transfer protocol the server can accept. +The site generation can be done anywhere, even on your own PC, and the generated files can be moved to the server by any file-transfer protocol the server can accept. -For small sites with a single author that are not updated too often, it is perfectly practical for authors to install the SSG software on their PC, and to keep and edit their content right there. Then, when they publish a new post, to run the SSG app and drag-and-drop the updated files into their favourite secure FTP client. +**BART - confused on the next paragraph - why use an SFTP client if the site is local on their PC? If that's not what you meant then it needs rewording** -This is of course not practical for multi-author sites, so the SSG can be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the files on that server, and that the server can run the SSG app and transfer the generated site to the web server in some way. A SAMBA file share and a few scripts to trigger a re-build and use Secure FTP to copy the files would work just fine. +For small sites with a single author that are not updated too often, it is perfectly practical for authors to install the SSG software on their PC, and to keep and edit their content right there. Then, when they publish a new post, run the SSG app and dragand drop the updated files into their favourite secure FTP client. -These kinds of scripting approaches are simple bread and butter stuff to sysadmins, but they're not practical for home users, and, there are better tools available. +This is, of course, not practical for multi-author sites, so the SSG can be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the files on that server and that the server can run the SSG app and transfer the generated site to the web server in some way. A SAMBA file share and a few scripts to trigger a rebuild and use Secure FTP to copy the files would work just fine. + +These kinds of scripting approaches are simple bread-and-butter stuff to sysadmins, but they're not practical for home users, and, there are better tools available. #### Git+CI/CD and Static Site Generators are a Perfect Fit! -When you stop a think about it, you have a folder of text files that multiple people need to edit in a controlled way, and where changes need to trigger actions. That's no different to writing software! +**BART - you jumped into the middle here, saying we have a folder of text files - but how did that happen if this is a new heading and subject? Would it make sense to say it more like, "What if you had a simple folder of text files that multiple people needed to edit in a controlled way"?** + +When you stop and think about it, you have a folder of text files that multiple people need to edit in a controlled way, and where changes need to trigger actions. That's no different from writing software! Content creation can be done using your favourite text editor, usually in Markdown, and collaboration and editorial control can be handled by Git. No matter how complex your editorial process is, it can be implemented using Git features like branches, permissions, and pull requests. Content publishing can then be automated using the Continuous Integration/Continuous Development (CI/CD) pipelines that are now ubiquitous in Git environments. CI/CD pipelines are effectively scripts that run in the cloud that are triggered by Git events like commits to specific branches. GitHub supports CI/CD through GitHub Actions. -This is the process by which these very show notes were published. Myself and Allison are both authors with full permissions on the Git repository for these notes, which contains a Markdown files with the content. We use a temporary Git branch to draft each new instalment, and then when we're ready to publish the instalment we merge the temporary branch into `master` which triggers a GitHub Actions action that generates and publishes the updated site. +This is the process by which these very show notes were published. Myself and Allison are both authors with full permissions on the Git repository for these notes. The repo contains Markdown files with the content. We use a temporary Git branch to draft each new instalment, and then when we're ready to publish the instalment, we merge the temporary branch into `master` which triggers a GitHub Actions action that generates and publishes the updated site. + +In terms of editorial process, it's very simple — myself and Allison are peers with full publishing power, the community are contributors who use Pull Requests to submit proposed fixes and changes to us. We can then choose to accept those changes and merge them into `master` (triggering a site rebuild), or we can reject them (which we almost never do). -In terms of editorial process, it's very simple — myself and Allison are peers with full publishing power, the community are contributors who use Pull Requests to submit proposed fixes and changes to us. We can then choose to accept those changes and merge them into `master` (triggering a site re-build), or we can reject them (which we almost never do). +**BART - I will have trouble with saying this is very simple. I know it's simple for you, but it still isn't for me. I have never successfully accepted a pull request. I've tried and failed and eventually you see it and do it. Merge conflicts still defeat me to this day. I think if you're going to say "simple" it would be valid to say "it's simple for those who are comfortable with Git and GitHub in their normal software development process." WordPress is far and away simpler for me and Steve to collaborate and even roll back changes.** #### Pros & Cons The infrastructure requirements for a static site are generally simpler than those for dynamic sites. They range from simply a PC with a few apps and the most basic of web hosting to a Git + CI/CD infrastructure and a basic web server. Regardless of your scale, a static site will be architecturally simpler and cheaper to run than an equivalently sized dynamic site. -OK, so why does the whole web not run on static site generators? Because there are of course some down-sides too 🙂 +OK, so why does the whole web not run on static site generators? Because there are, of course, some downsides, too 🙂 1. Publication of new content is never real-time. Sure, you can automate it with triggers, but the entire site needs to be re-built each time, so it will always take a few minutes -2. User interaction needs to be off-loaded from the site — you can embed 3rd-party cloud services like Disqus, or you can simply utilise social media for audience engagement, but what ever you do, that engagement will not be tightly integrated with your CMS, it will be in some way external to it +2. Interaction with your readers needs to be off-loaded from the site — you can embed 3rd-party cloud discussion group services like [Disqus](https://disqus.com), or you can simply utilise social media for audience engagement. Whatever you do, that engagement will not be tightly integrated with your CMS; it will be in some way external to it. This adds a layer of complexity to this approach. 3. While the details will vary widely, in general, the interface for authors will not be as simple and self-contained as a unified web interface. Depending on who your authors are, and what their technological experience is, that might be a bug or a feature, but regardless, it's something you need to consider carefully ### Which to Choose? -It's vital to realise that neither approach is objectively better or worse, each has advantages and disadvantages. The question is not *"which approach is best?"*, but *"which approach is best for me/us?"*. Who you are, what your goals are, and what resources you have at your disposal all need to feed into your evaluations. +It's vital to realise that neither approach is objectively better or worse. Each has advantages and disadvantages. The question is not *"which approach is best?"*, but *"which approach is best for me/us?"*. Who you are, what your goals are, and what resources you have at your disposal all need to feed into your evaluations. Some key questions to consider: @@ -121,34 +129,36 @@ Some key questions to consider: 3. Do they have strong feelings about tooling choices? 4. Are they employees you can command, or volunteers you need to attract? -At the extremes it's usually quite obvious what the right fit is. Let's take two really popular sites as examples. +At the extremes, it's usually quite obvious what the right fit is. Let's take two really popular sites as examples. First, let's consider Ars Technica — it has tens if not hundreds of authors, editors, and other contributors, new content is published many times an hour, and they integrate user comments into their pages. It should come as no surprise that they use a dynamic system that must cost an absolute fortune to run because it needs to support a massive audience. -But now let's consider John Gruber's Daring Fireball Apple site — this is no more of a hobby project than Ars Technica, running that site puts food on John's table, but, only on John's table. He has no employees, and no complex editorial process. He publishes a handful of times a day at most, and has never allowed any kind of user-submitted content onto his site. He also has a massive audience, so he needs his site to be able to handle that load without costing him more than he can make from sponsorships. +But now let's consider John Gruber's Daring Fireball Apple site. This is no more of a hobby project than Ars Technica — running that site puts food on John's table, but, only on John's table. He has no employees and no complex editorial process. He publishes a handful of times a day at most and has never allowed any kind of user-submitted content onto his site. He also has a massive audience, so he needs his site to be able to handle that load without costing him more than he can make from sponsorships. John uses a static site generator, and it really is the perfect fit for him. -Both Ars and Daring Fireball are huge site, neither are in any way amateur, both have made the prefect technical decision for their needs, and one has opted for a dynamic site, and one for a statically generated one. +Both Ars and Daring Fireball are huge sites, neither is in any way amateur, both have made the perfect technical decision for their needs, and one has opted for a dynamic site, and one for a statically generated one. -The annoying thing is that for smaller sites the tradeoffs tend to be less clear. For decades I've operated both my personal website and the site for my podcasts as dynamic sites, but I'm completely fed up with both. I'm done with managing servers and databases and paying substantial hosting bills. I want something simpler and cheaper, so I'm spending 2025 moving both of those sites to static site generators. Specifically, I'm moving both to GitHub Pages. +The annoying thing is that for smaller sites, the tradeoffs tend to be less clear. For decades I've operated both my personal website and the site for my podcasts as dynamic sites, but I'm completely fed up with both. I'm done with managing servers and databases and paying substantial hosting bills. I want something simpler and cheaper, so I'm spending 2025 moving both of those sites to static site generators. Specifically, I'm moving both to GitHub Pages. ## Why You Might Consider Using GitHub Pages Before we finish this instalment with a big-picture overview of how GitHub Pages works, let's just look at some reasons you might be interested in learning a little more about GitHub Pages. -1. Free web hosting 🙂 — sure, it's limited to static content, but you can use GitHub Actions with static site generators to run complex site, and, you can even use your own domains names if you like! -2. A simple way to publish documentation with any code you publish on GitHub. -3. You can host the kind of client-side web apps we've been developing in this series without even learning about Static Site Generators. +1. Free web hosting 🙂 — sure, it's limited to static content, but you can use GitHub Actions with static site generators to run complex sites, and you can even use your own domain names if you like! +2. A simple way to publish documentation with any code you publish on GitHub. **BART: not sure what this means - docs with code?** +3. You can host the kind of client-side web apps we've been developing in Programming By Stealth without even learning about Static Site Generators. **BART: even Allison has done this with her [Elapsed Time Adder app](https://podfeet.github.io/time-adder/)** 4. If you're the kind of person who's enjoying this series, your skillset and mindset are likely to line up well with how GitHub Pages does things. ## A Big-Picture Overview of GitHub Pages +**BART: I think some kind of narrowing of the scope needs to go here because some of this doesn't apply to deploying web apps (I don't think). I'm pretty sure I never went near Jekyll for example. Maybe this part should say something like, "focusing on the non-web app use of GitHub Pages"?** + GitHub Pages converts content within a GitHub Git repository into a published web page using GitHub Actions. The default publication action uses a somewhat customised and extended version of the open source Static Site Generator [Jekyll](https://jekyllrb.com). -GitHub Pages can be configured to serve HTML, CSS & Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)), but when used in its default configuration as a content management system you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). +GitHub Pages can be configured to serve HTML, CSS, and Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)). When used in its default configuration as a content management system, you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). Some very basic aspects of GitHub Pages' operation are configured in the GitHub web interface, but most of the configuration is managed via a YAML settings file. @@ -159,7 +169,11 @@ To truly customise a GitHub Pages site you need to extend an existing Jekyll the 1. The [Liquid templating engine](https://shopify.github.io/liquid/) created by Shopify, which in turn leverages the [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) templating engine for data processing. 2. The CSS pre-processor [Sass](https://sass-lang.com) -GitHub Pages in no way enforces the use of Bootstrap, but given that we've relied heavily on it throughout this series, and that it's customisation features are implemented in Sass, we'll be using [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) with GitHub Pages in this series. +**BART: um...what are these? gonna ask way lotta questions...** + +GitHub Pages in no way enforces the use of Bootstrap, but given that we've relied heavily on it throughout this series, and that its customisation features are implemented in Sass, we'll be using [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) with GitHub Pages in this series. + +**BART: I see NodeJS & NPM in the list below but you haven't mentioned them in the overview. Do we need to know how they fit in?** Putting it all together, you can see just how many technologies are in the mix here, how some show up repeatedly, and that while most are familiar to us already, quite a few are not: @@ -184,10 +198,10 @@ Putting it all together, you can see just how many technologies are in the mix h ## Final Thoughts -Our approach in this series will be to break the broad topic down into two distinct section, each solving a different problem. If you're envisaging this as a 50/50 split, don't, it will most likely prove to be much closer to a 10/90 split! +Our approach in this series will be to break the broad topic down into two distinct sections, each solving a different problem. If you're envisaging this as a 50/50 split, don't, it will most likely prove to be much closer to a 10/90 split! The first *problem to be solved* will be **using GitHub Pages to host** the **HTML+CSS+Javascript web apps** we were developing earlier in this series. This use of GitHub Pages ignores Jekyll completely, but allows us to explore how GitHub Actions work, and in the process get a taste for how the CI/CD workflows we've mentioned in passing in recent instalments work. We'll probably wrap this up in a single instalment. -The remainder of the series will focus on solving the much more expansive problem of **using GitHub Pages with Jekyll as a content management system**. The end-goal for this much larger second act will be a content management system with an entirely bespoke theme based on Bootstrap with customisations that supports rich taxonomies. We'll build this up gradually, starting with the most simplistic base theme possible with Bootstrap installed in a customisable way, and we'll build things up from there, starting with the basics of each of the new technologies early in the series, and then filling ever more of the detail in all the new technologies as we progress to ever more advanced use-cases. +The remainder of the series will focus on solving the much more expansive problem of **using GitHub Pages with Jekyll as a content management system**. The end goal for this much larger second act will be a content management system with an entirely bespoke theme based on Bootstrap with customisations that supports rich taxonomies. We'll build this up gradually, starting with the most simplistic base theme possible with Bootstrap installed in a customisable way, and we'll build things up from there, starting with the basics of each of the new technologies early in the series, and then filling ever more of the detail in all the new technologies as we progress to ever more advanced use cases. -From the very start of the series we'll built everything in such a way that we can test our sites locally on our own PCs before pushing our changes to GitHub for publication to the internet. This will greatly speed up the development process by allowing us to debug our sites with minimal friction. +From the very start of the series we'll built everything in such a way that we can test our sites locally on our own local computers before pushing our changes to GitHub for publication to the internet. This will greatly speed up the development process by allowing us to debug our sites with minimal friction. From f4ea300119f2a3eb357ade060b57748f6be902d6 Mon Sep 17 00:00:00 2001 From: Bart Busschots Date: Sat, 1 Feb 2025 09:49:55 +0000 Subject: [PATCH 2/6] Feat: PBS 175 questions addressed --- docs/_pbs/pbs175.md | 36 ++++++++++++++---------------------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/docs/_pbs/pbs175.md b/docs/_pbs/pbs175.md index cb5a9e0..636e66f 100644 --- a/docs/_pbs/pbs175.md +++ b/docs/_pbs/pbs175.md @@ -76,31 +76,27 @@ Static Site Generators (SSG) like GitHub Pages turn things on their head complet Static Site Generators generally store their content in files on the file system, so there is no database, and hence no need for a database server. The web server doesn't do any rendering, so its load is minimal, and it doesn't require any server-side languages. -The site generation can be done anywhere, even on your own PC, and the generated files can be moved to the server by any file-transfer protocol the server can accept. +While the generated files need to make their way to a web server to be published to the internet, the generation itself can be done anywhere. You can even do the generation on your own PC and then move the generated files to your web server by any file-transfer protocol the server can accept. -**BART - confused on the next paragraph - why use an SFTP client if the site is local on their PC? If that's not what you meant then it needs rewording** +For small sites with a single author that are not updated too often, it is perfectly practical for authors to install their SSG software on their PC and keep and manage the content files for their site like they would any other documents. Then, each time the update their content they'd run their SSG software to generated the updated website files, connect to their web server with their favourite file transfer client, and just drag-and-drop the newly generated website files to their server to publish the updated site. -For small sites with a single author that are not updated too often, it is perfectly practical for authors to install the SSG software on their PC, and to keep and edit their content right there. Then, when they publish a new post, run the SSG app and dragand drop the updated files into their favourite secure FTP client. - -This is, of course, not practical for multi-author sites, so the SSG can be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the files on that server and that the server can run the SSG app and transfer the generated site to the web server in some way. A SAMBA file share and a few scripts to trigger a rebuild and use Secure FTP to copy the files would work just fine. +This is, of course, not practical for multi-author sites, so and SSG can also be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the content files on that server, that the server can run the SSG app to convert the content files to the website files, and then transfer those generated files the web server in some way. A SAMBA file share and a few scripts to trigger a rebuild and use Secure FTP to copy the files would work just fine. These kinds of scripting approaches are simple bread-and-butter stuff to sysadmins, but they're not practical for home users, and, there are better tools available. #### Git+CI/CD and Static Site Generators are a Perfect Fit! -**BART - you jumped into the middle here, saying we have a folder of text files - but how did that happen if this is a new heading and subject? Would it make sense to say it more like, "What if you had a simple folder of text files that multiple people needed to edit in a controlled way"?** +When you stop and think about it, the site content files are just a folder of text files that multiple people need to edit in a controlled way, and where changes to those files need to trigger actions. That's no different from writing software where you have a folder of source code that needs to be edited by multiple people on a controlled way and then trigger some kind of build process to test and publish the updated app or library or what ever! -When you stop and think about it, you have a folder of text files that multiple people need to edit in a controlled way, and where changes need to trigger actions. That's no different from writing software! +That means we can use the kind of tooling perfected by developers collaborating on software to collaborate on a statically generated website. -Content creation can be done using your favourite text editor, usually in Markdown, and collaboration and editorial control can be handled by Git. No matter how complex your editorial process is, it can be implemented using Git features like branches, permissions, and pull requests. +The content creation can be done using your favourite text editor, usually in Markdown, and collaboration and editorial control can be handled by Git. No matter how complex your editorial process is, it can be implemented using Git features like branches, permissions, and pull requests. Content publishing can then be automated using the Continuous Integration/Continuous Development (CI/CD) pipelines that are now ubiquitous in Git environments. CI/CD pipelines are effectively scripts that run in the cloud that are triggered by Git events like commits to specific branches. GitHub supports CI/CD through GitHub Actions. -This is the process by which these very show notes were published. Myself and Allison are both authors with full permissions on the Git repository for these notes. The repo contains Markdown files with the content. We use a temporary Git branch to draft each new instalment, and then when we're ready to publish the instalment, we merge the temporary branch into `master` which triggers a GitHub Actions action that generates and publishes the updated site. - -In terms of editorial process, it's very simple — myself and Allison are peers with full publishing power, the community are contributors who use Pull Requests to submit proposed fixes and changes to us. We can then choose to accept those changes and merge them into `master` (triggering a site rebuild), or we can reject them (which we almost never do). +This is the process by which these very show notes were published. Myself and Allison are both authors with full permissions on the Git repository for these notes. The repo contains Markdown files with the content. We use a temporary Git branch to draft each new instalment, and then when we're ready to publish the instalment, we merge the temporary branch into `master` which triggers a GitHub Actions action that uses a static site generator to convert the Markdown files into the files for the website and publishes those generated files to a web server to update the website. -**BART - I will have trouble with saying this is very simple. I know it's simple for you, but it still isn't for me. I have never successfully accepted a pull request. I've tried and failed and eventually you see it and do it. Merge conflicts still defeat me to this day. I think if you're going to say "simple" it would be valid to say "it's simple for those who are comfortable with Git and GitHub in their normal software development process." WordPress is far and away simpler for me and Steve to collaborate and even roll back changes.** +In terms of editorial process (not necessarily technical implementation), it's very simple — myself and Allison are peers with full publishing power, the community are contributors who use Pull Requests to submit proposed fixes and changes to us. We can then choose to accept those changes and merge them into `master` (triggering a site rebuild), or we can reject them (which we almost never do). #### Pros & Cons @@ -148,17 +144,17 @@ The annoying thing is that for smaller sites, the tradeoffs tend to be less clea Before we finish this instalment with a big-picture overview of how GitHub Pages works, let's just look at some reasons you might be interested in learning a little more about GitHub Pages. 1. Free web hosting 🙂 — sure, it's limited to static content, but you can use GitHub Actions with static site generators to run complex sites, and you can even use your own domain names if you like! -2. A simple way to publish documentation with any code you publish on GitHub. **BART: not sure what this means - docs with code?** -3. You can host the kind of client-side web apps we've been developing in Programming By Stealth without even learning about Static Site Generators. **BART: even Allison has done this with her [Elapsed Time Adder app](https://podfeet.github.io/time-adder/)** +2. A simple way to publish the matching documentation with any code share with others on GitHub. +3. You can host the kind of client-side web apps we've been developing in Programming By Stealth without even learning about Static Site Generators. (Like Allison has done with her [Elapsed Time Adder app](https://podfeet.github.io/time-adder/)!) 4. If you're the kind of person who's enjoying this series, your skillset and mindset are likely to line up well with how GitHub Pages does things. ## A Big-Picture Overview of GitHub Pages -**BART: I think some kind of narrowing of the scope needs to go here because some of this doesn't apply to deploying web apps (I don't think). I'm pretty sure I never went near Jekyll for example. Maybe this part should say something like, "focusing on the non-web app use of GitHub Pages"?** +GitHub Pages converts content within a GitHub Git repository into a published web page using GitHub Actions. The default publication action uses a somewhat customised and extended version of the open source Static Site Generator [Jekyll](https://jekyllrb.com). -GitHub Pages converts content within a GitHub Git repository into a published web page using GitHub Actions. The default publication action uses a somewhat customised and extended version of the open source Static Site Generator [Jekyll](https://jekyllrb.com). +> Note that by default Jekyll is always doing the site generation, but its presence can be invisible. If you give it only regular HTML, CSS, and JavaScript files as input, then it will pass them straight through to the 'generated' site un-changed. It will have checked each file for front matter and template strings, found none, and hence made no changes. This is what happens each time Allison updates her Elapsed Time Adder app. -GitHub Pages can be configured to serve HTML, CSS, and Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)). When used in its default configuration as a content management system, you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). +But GitHub Pages doesn't have to use Jekyll, it can be configured to serve HTML, CSS, and Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)). When used as a content management system in its default configuration, you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). Some very basic aspects of GitHub Pages' operation are configured in the GitHub web interface, but most of the configuration is managed via a YAML settings file. @@ -169,18 +165,14 @@ To truly customise a GitHub Pages site you need to extend an existing Jekyll the 1. The [Liquid templating engine](https://shopify.github.io/liquid/) created by Shopify, which in turn leverages the [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) templating engine for data processing. 2. The CSS pre-processor [Sass](https://sass-lang.com) -**BART: um...what are these? gonna ask way lotta questions...** - GitHub Pages in no way enforces the use of Bootstrap, but given that we've relied heavily on it throughout this series, and that its customisation features are implemented in Sass, we'll be using [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) with GitHub Pages in this series. -**BART: I see NodeJS & NPM in the list below but you haven't mentioned them in the overview. Do we need to know how they fit in?** - Putting it all together, you can see just how many technologies are in the mix here, how some show up repeatedly, and that while most are familiar to us already, quite a few are not: * Git & GitHub ✅ * GitHub Actions ❌ * YAML ✅ - * NodeJS & NPM ✅ + * NodeJS & NPM ✅ (for publishing web apps with Webpack rather than than Jekyll in pass-through mode) * HTML, CSS & JavaScript ✅ * NodeJS & NPM ✅ * Bootstrap ✅ From 1556cae9b04a4e02960f018b14827b6b4af21561 Mon Sep 17 00:00:00 2001 From: Bart Busschots Date: Sat, 1 Feb 2025 16:53:34 +0000 Subject: [PATCH 3/6] Fix: formatting --- docs/_pbs/pbs175.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_pbs/pbs175.md b/docs/_pbs/pbs175.md index 636e66f..0dedaa8 100644 --- a/docs/_pbs/pbs175.md +++ b/docs/_pbs/pbs175.md @@ -152,7 +152,8 @@ Before we finish this instalment with a big-picture overview of how GitHub Pages GitHub Pages converts content within a GitHub Git repository into a published web page using GitHub Actions. The default publication action uses a somewhat customised and extended version of the open source Static Site Generator [Jekyll](https://jekyllrb.com). -> Note that by default Jekyll is always doing the site generation, but its presence can be invisible. If you give it only regular HTML, CSS, and JavaScript files as input, then it will pass them straight through to the 'generated' site un-changed. It will have checked each file for front matter and template strings, found none, and hence made no changes. This is what happens each time Allison updates her Elapsed Time Adder app. +> Note that by default Jekyll is always doing the site generation, but its presence can be invisible. If you give it only regular HTML, CSS, and JavaScript files as input, then it will pass them straight through to the 'generated' site un-changed. It will have checked each file for front matter and template strings, found none, and hence made no changes. This is what happens each time Allison updates her Elapsed Time Adder app. +{: .aside} But GitHub Pages doesn't have to use Jekyll, it can be configured to serve HTML, CSS, and Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)). When used as a content management system in its default configuration, you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). From f6b058b070a27cebedc52021a76a8798b5701596 Mon Sep 17 00:00:00 2001 From: "allison@podfeet.com" Date: Sat, 1 Feb 2025 16:36:40 -0800 Subject: [PATCH 4/6] Fix: typos --- docs/_pbs/pbs175.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/_pbs/pbs175.md b/docs/_pbs/pbs175.md index 0dedaa8..eabba0e 100644 --- a/docs/_pbs/pbs175.md +++ b/docs/_pbs/pbs175.md @@ -72,15 +72,15 @@ But you do of course get some advantages: ### Publication-Time Rendering — Static Site Generators -Static Site Generators (SSG) like GitHub Pages turn things on their head completely. The entire site is rendered to HTML, CSS & JavaScript when new content is published, and those pre-generated files are copied to a basic web server that serves those same simple HTML files to all visitors. +Static Site Generators (SSGs) like GitHub Pages turn things on their head completely. The entire site is rendered to HTML, CSS & JavaScript when new content is published, and those pre-generated files are copied to a basic web server that serves those same simple HTML files to all visitors. Static Site Generators generally store their content in files on the file system, so there is no database, and hence no need for a database server. The web server doesn't do any rendering, so its load is minimal, and it doesn't require any server-side languages. While the generated files need to make their way to a web server to be published to the internet, the generation itself can be done anywhere. You can even do the generation on your own PC and then move the generated files to your web server by any file-transfer protocol the server can accept. -For small sites with a single author that are not updated too often, it is perfectly practical for authors to install their SSG software on their PC and keep and manage the content files for their site like they would any other documents. Then, each time the update their content they'd run their SSG software to generated the updated website files, connect to their web server with their favourite file transfer client, and just drag-and-drop the newly generated website files to their server to publish the updated site. +For small sites with a single author that are not updated too often, it is perfectly practical for authors to install their SSG software on their PC and keep and manage the content files for their site like they would any other documents. Then, each time they update their content they'd run their SSG software to generate the updated website files, connect to their web server with their favourite file transfer client, and just drag-and-drop the newly generated website files to their server to publish the updated site. -This is, of course, not practical for multi-author sites, so and SSG can also be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the content files on that server, that the server can run the SSG app to convert the content files to the website files, and then transfer those generated files the web server in some way. A SAMBA file share and a few scripts to trigger a rebuild and use Secure FTP to copy the files would work just fine. +This is, of course, not practical for multi-author sites, so an SSG can also be run on a centralised server of some kind. The key requirement is that authors have a mechanism for accessing the content files on that server, that the server can run the SSG app to convert the content files to the website files, and then transfer those generated files to the web server in some way. A SAMBA file share and a few scripts to trigger a rebuild and use Secure FTP to copy the files would work just fine. These kinds of scripting approaches are simple bread-and-butter stuff to sysadmins, but they're not practical for home users, and, there are better tools available. @@ -121,9 +121,10 @@ Some key questions to consider: 5. What technical skills do you have at your disposal for operating the site? 6. How are your authors with technology? 1. What skills do they have? - 2. How would they feel about learning new skills? - 3. Do they have strong feelings about tooling choices? + 2. How would they feel about learning new skills? + 3. Do they have strong feelings about tooling choices? 4. Are they employees you can command, or volunteers you need to attract? +7. How much content are you likely to create? SSGs may have total size limitations ([GitHub Pages limit is 1GB per repo and individual files less than 100MB](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#usage-limits)) At the extremes, it's usually quite obvious what the right fit is. Let's take two really popular sites as examples. @@ -152,7 +153,7 @@ Before we finish this instalment with a big-picture overview of how GitHub Pages GitHub Pages converts content within a GitHub Git repository into a published web page using GitHub Actions. The default publication action uses a somewhat customised and extended version of the open source Static Site Generator [Jekyll](https://jekyllrb.com). -> Note that by default Jekyll is always doing the site generation, but its presence can be invisible. If you give it only regular HTML, CSS, and JavaScript files as input, then it will pass them straight through to the 'generated' site un-changed. It will have checked each file for front matter and template strings, found none, and hence made no changes. This is what happens each time Allison updates her Elapsed Time Adder app. +> Note that by default, Jekyll is always doing the site generation, but its presence can be invisible. If you give it only regular HTML, CSS, and JavaScript files as input, then it will pass them straight through to the 'generated' site unchanged. It will have checked each file for front matter and template strings, found none, and hence made no changes. This is what happens each time Allison updates her Elapsed Time Adder app. {: .aside} But GitHub Pages doesn't have to use Jekyll, it can be configured to serve HTML, CSS, and Javascript generated through just about any build process (including Webpack which we learned about in instalments [137](./pbs137), [138](./pbs138) & [139](./pbs139)). When used as a content management system in its default configuration, you write your content in Markdown and add your metadata as YAML front matter at the top of your Markdown files. This is one of the reasons we covered YAML in instalments [168](./pbs168) & [169](./pbs169). @@ -163,7 +164,7 @@ GitHub provides a number of built-in themes, and using the configuration file, i To truly customise a GitHub Pages site you need to extend an existing Jekyll theme or create your own from scratch. Being an open source project, Jekyll leverages other open source technologies within it's themes, including: -1. The [Liquid templating engine](https://shopify.github.io/liquid/) created by Shopify, which in turn leverages the [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) templating engine for data processing. +1. The open source [Liquid templating engine](https://shopify.github.io/liquid/) created by Shopify, which in turn leverages the [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) templating engine for data processing. 2. The CSS pre-processor [Sass](https://sass-lang.com) GitHub Pages in no way enforces the use of Bootstrap, but given that we've relied heavily on it throughout this series, and that its customisation features are implemented in Sass, we'll be using [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) with GitHub Pages in this series. From 650e02ff26f5ad0728fe92163f51a9891940b823 Mon Sep 17 00:00:00 2001 From: "allison@podfeet.com" Date: Sat, 1 Feb 2025 16:37:20 -0800 Subject: [PATCH 5/6] Feat: Add matching podcast episode --- docs/_pbs/pbs175.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/_pbs/pbs175.md b/docs/_pbs/pbs175.md index eabba0e..ce938fe 100644 --- a/docs/_pbs/pbs175.md +++ b/docs/_pbs/pbs175.md @@ -13,7 +13,11 @@ In this first instalment we'll set the scene, explaining the difference between ## Matching Podcast Episode -TO DO + + +You can also Download the MP3 + +Read an unedited, auto-generated transcript with chapter marks: PBS_2025_02_01 ## What Problems Do CMS Platforms Solve? From 31de73857cd28f5f693690b52baa38bccf93c81a Mon Sep 17 00:00:00 2001 From: Bart Busscots Date: Sun, 2 Feb 2025 01:36:03 +0000 Subject: [PATCH 6/6] Delete docs/_pbs/pbsXXX-GitHubPagesPrep.md --- docs/_pbs/pbsXXX-GitHubPagesPrep.md | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 docs/_pbs/pbsXXX-GitHubPagesPrep.md diff --git a/docs/_pbs/pbsXXX-GitHubPagesPrep.md b/docs/_pbs/pbsXXX-GitHubPagesPrep.md deleted file mode 100644 index 5d1462e..0000000 --- a/docs/_pbs/pbsXXX-GitHubPagesPrep.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Static Site Generators -instalment: xxx -miniseries: GitHub Pages -creators: [bart, allison] -date: -opengraph: - audio: ---- -## Resources - -- Docs explaining how to enable Jekyll on GitHub Page — [docs.github.com/…](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll) (need a repo configured to use Pages first) -- Docs for testing GitHub pages locally — [docs.github.com/…](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll) (can't do until basic site up and running)