Version 1.1.0 (spectrasecure#1)

# Arise v1.1.0

---

## Changelog

- Bumped `actions/checkout@v2` to `actions/checkout@v4`. No impact from this change.
- Removed `sed` from the metadata tag evaluation in `build_header`. Replaced with Bash native pattern matching so that this evaluation is safer.
- Added checks to automatically rewrite any XML reserved characters (&<>'") as their escape codes when present in page metadata (title, author, etc).
    - Rewrote the way a majority of the page metadata values are parsed in `get_page_metadata` to make the parsing more robust. This was necessary because previously unescaped double quotes (`"`) would break the parser. The workaround was to use escape codes, but if we're automatically parsing escape codes then we need a way to put these characters in unescaped now.
    - Added a CI test suite to build the default site and test to make sure that the XML reserved characters are getting properly escaped. This is helpful because it allows me to more continuously ensure that commits I make in dev don't break the site.
- Added a Smart Deploy step in the deployment workflow to check whether the triggering branch is `main` or not so that CICD can intelligently deploy the site to either production or staging depending on what branch triggered the deployment.

Author: neonspectra

.github/workflows/arise-deploy.yml

@@ -11,11 +11,6 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Allow one concurrent deployment
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
-
 # Default to bash
 defaults:
   run:
@@ -26,8 +21,24 @@ jobs:
     runs-on: ubuntu-latest
     name: Deploy Arise
     steps:
+      - name: Check if we should deploy to prod or staging
+        run: |
+          echo "SMART DEPLOY"
+          echo "============"
+          echo "We only want to deploy to prod if the branch that triggered this workflow is 'main'. Otherwise, we want the site to be deployed to staging..."
+          echo ""
+          if [[ $GITHUB_REF == 'refs/heads/main' ]]; then
+              # Feel free to change the value of OUTPUT_BRANCH. This is where Arise artefacts will be deployed for production.
+              echo "OUTPUT_BRANCH=html" >> "$GITHUB_ENV"
+              echo "Workflow running from main branch. Pushing results to production deployment branch (html)."
+          else
+              # Feel free to change the value of OUTPUT_BRANCH. This is where Arise artefacts will be deployed for staging.
+              echo "OUTPUT_BRANCH=html-staging" >> "$GITHUB_ENV"
+              echo "Workflow running from a development branch. Pushing results to staging deployment branch (html-staging)."
+          fi
+
       - name: git-checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install pandoc
         run: sudo apt-get install -y pandoc
@@ -39,7 +50,7 @@ jobs:
         uses: s0/git-publish-subdir-action@develop
         env:
           REPO: self
-          BRANCH: html # Feel free to change this. This is where Arise artefacts will be pushed.
+          BRANCH: ${{ env.OUTPUT_BRANCH }} # If you want to change this, change it in the step above. This allows us to intelligently deploy to production from main or staging if we're on a dev branch.
           FOLDER: arise-out # The Arise build output location. Don't change this.
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Handled automatically -- Don't change this unless you're pushing to a different repo
           MESSAGE: "Commit: ({sha}) {msg}" # Copies commit msg from main to the deploy version branch

.github/workflows/ci-xml-reserved-characters.yml

@@ -0,0 +1,39 @@
+# .github/workflows/ci-xml-reserved-characters.yml
+name: CI Test - XML Reserved Character Metadata Sanitisation
+
+on:
+  # Runs on everything except the main branch since this is only a concern for dev.
+  push:
+    branches:
+      - '**'
+      - '!main'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "xml-reserved-characters"
+  cancel-in-progress: true
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Check XML Sanitisation
+    steps:
+      - name: git-checkout
+        uses: actions/checkout@v4
+
+      - name: Install pandoc
+        run: sudo apt-get install -y pandoc
+
+      - name: Build Arise
+        run: bash arise build
+    
+      - name: Run test suite
+        run: bash ci/xml-reserved-characters.sh

README.md

@@ -7,22 +7,22 @@
 
 ## Overview
 
-There was a time before React, before Wordpress, and before even javascript and php. And the webmasters who ran the 'net back then made do with what they had. They wrangled their webservers to the fullest and they hacked together sites that could do what they need-- somehow. 
+There was a time before React, before Wordpress, and before even javascript and php. And the webmasters who ran the 'net back then made do with what they had. They wrangled their webservers to the fullest and they hacked together sites that could do what they need. 
 
-The web has grown up a lot since then, but unfortunately many of the modern tools we've built on top of are just way too complicated to maintain on the day-to-day without a fully staffed corporate webdev team.
+The web has grown up a lot since then, but the mentality of "move fast and break things" has created a landscape of flaky tools never meant to last more than a few years without constant laborious maintenance. You should be able to run a functional and pleasant website without needing to be a fully staffed corporate webdev team.
 
-The goal of Arise is to take the lessons of yesteryear and make something novel. Arise is a cloud-native static site generator written in Bash, designed to be a fusion of ultra-stable timeless 90s technology and modern DevOps paradigms. Arise is designed around use cases like individual blogs and personal websites.
+The goal of Arise is to take the lessons of yesteryear and make something novel. Arise is a cloud-native static site generator written in Bash, designed to be a fusion of ultra-stable 90s technology and modern DevOps paradigms. Arise is designed around use cases like individual blogs and personal websites.
 
 ## Why Use Arise
 
-Arise is written in Bash with very few dependencies outside of the standard GNU toolchain. Arise is designed with longterm simplicity and maintainability in mind. It is unlikely that the core code Arise runs on will break in the near future due to language or dependency updates.
+Arise is written in Bash with very few dependencies outside of the standard GNU toolchain. Arise is designed with long term simplicity and maintainability in mind. Beyond just being a static site generator that doesn't suck, the core development philosphy behind Arise is to minimise the risk of breaking in the near future due to language or dependency updates.
 
 Arise supports modern SEO features that are built into your pages out of the box without any extra effort necessary:
 - [OpenGraph](https://ogp.me/) and [TwitterCard](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards) support for rich embed details
 - Dynamically generated RSS feed
 - Dynamically generated search engine sitemap
 
-Arise is built to be practical and let you build a website that actually has real content on it and isn't just a single-page placeholder. Arise uses a modular page architecture with support for dynamically generated metadata-rich index pages to keep your site hierarchy traversable by end users.
+Arise is built to be practical and let you build a multi-page website that actually has real content on it. Arise uses a modular page architecture with support for dynamically generated metadata-rich index pages to keep your site hierarchy traversable by end users.
 
 ## Live Example
 
@@ -57,10 +57,19 @@ All of the documentation for getting started with Arise can be found within this
 - GNU `awk`
     - **Used for:** `evaluate_inline` - Function that performs inline bash snippet evaluations. This is disabled by default because this functionality is still WIP.
     - **Why:** Using `awk` in any capacity is the equivalent of staring into a horrific eldrich abyss not meant for mere mortals. Making those commands portable is another story entirely.
-- GNU `sed`
-    - **Used for:** `build_header` - Function that populates headers with metadata from page source files
-    Dependency for the header metadata tag population. 
-    - **Why:** This script makes use of the GNU version of the '-i' flag. BSD sed will not let you run inline sed replacements without forcing you to do an extra file write to create a backup of the original file, which you then have to run ANOTHER command to delete (literally why).
+- `sed`
+    - **Used for:**
+        - `get_page_metadata` - Used to pull out the metadata header in Arise markdown files for further processing. Also used for cleaning up relative URLs generated from folder hierarchy.
+        - `build_page` - Used to pull out the metadata header in Arise markdown files for further processing.
+        - `build_sitemap` - Used to clean up URLs into the tags RSS wants them in.
+        - `evaluate_inline` - Yeah, I don't even want to think about the horrors I wrote in this function. It's not currently in use, and I'm pretty sure it will get a full rewrite before it becomes active, IF it becomes active...
+    - **Why:** `sed` is useful for parsing data out of blocks of text quickly and easily. However, much dogfooding has revealed that `sed` tends to be pretty unsuited for this application. As such, it is largely on the chopping block for replacement with native Bash pattern matching where possible.
+
+## CI Testing
+
+For development purposes, we use CI testing to ensure that new code changes don't break Arise while in development. CI-related scripts are bundled in `/ci` and CI-related workflows are named with the convention of `/.github/workflows/ci-*`. **As a non-maintainer who is not making modifications to the Arise source code, you can simply delete (or just ignore) the CI tests if you don't need them.**
+
+In order to maximise the amount of [dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) we do in testing, CI tests are run against actual pages bundled as part of the default website (https://ari.se.net). This means that once you replace the default site with your own custom website, the CI tests will break because the dummy pages they rely on no longer exist.
 
 ## Wishlist / To-Do / Feature Ideas
 - Refactor inline bash evaluation function and enable its usage. Right now it only works on very tiny/simple snippets. The main reason I wrote the logic was because I thought it would be funny to implement (it was). Some refactoring is absolutely necessary to make this feature practical/useful and not just a good meme.

arise

@@ -1,8 +1,8 @@
 #!/bin/bash
 ######################################
 # ARISE
-# https://github.com/neonspectra/arise
-arise_version="1.0.0"
+# https://github.com/spectrasecure/arise
+arise_version="1.1.0"
 ######################################
 
 ##############################################################

arise-source/config/footer.html

@@ -1,7 +1,7 @@
 
         <!-- Page Footer -->
         <div class="footer">
-                <p>Copyleft &copy 2022 <a href="https://twitter.com/spectrasecure">Spectra Secure</a> • All wrongs reserved</p>
+                <p>Copyleft &copy 2023 <a href="https://spectrasecu.re">Spectra Secure</a> • All wrongs reserved</p>
                 <p>Built with 💚 using <a href="https://github.com/spectrasecure/arise">Arise</a>, a cloud-native static site generator written in Bash.</p>
         </div>
         <!-- End Page Footer -->

arise-source/index.md

@@ -14,17 +14,17 @@ rss_hide:: "true"
 
 # Retro doesn't have to be regressive
 
-Arise is a static site generator written in Bash, designed to be a fusion of ultra-stable timeless 90s technology and modern DevOps paradigms. Arise is designed around use cases like individual blogs and personal websites.
+Arise is a static site generator written in Bash, designed to be a fusion of ultra-stable 90s technology and modern DevOps paradigms. Arise is designed around use cases like individual blogs and personal websites.
 
-You ever see one of those nineties zombie websites that hasn't been updated in like thirty years but is still somehow running today? [Stuff like this](http://home.mcom.com/home/welcome.html). Can you imagine a modern website lasting that long without becoming a completely broken mess?
+Let me tell you why Arise exists. You ever seen one of those nineties zombie websites that hasn't been updated in like thirty years but is still somehow running today? [Stuff like this](http://home.mcom.com/home/welcome.html). Can you imagine a modern website lasting that long without becoming a completely broken mess?
 
-We live in a world where the mindset of "move fast, break things" has trained web developers to keep stacking more and more overdesigned trash, one node framework or polyfill at a time, onto our websites. Over time, we've lost sight of the fact that at the end of the day a website is just a tool to share information with other people.
+We live in a world where the mindset of "move fast, break things" has trained web developers to keep stacking more and more overdesigned trash onto their websites, one node framework or polyfill at a time. Over time, we've collectively lost the plot and forgotten that websites are ultimately a tool to share information with other people.
 
 Arise was built to show that you can take simple technology like Bash that is so set in stone as to be basically indestructible and use it to create modern web tools.
 
 ## Simplify deployment
 
-90s websites may have lasted forever, but no one likes setting up a janky webserver on a computer in their closet. Arise is a modern cloud-native application that supports easy deployment to your cloud static site host of choice.
+90s websites may have been robust in their simplicity, but no one likes setting up a janky webserver on a computer in their closet. Arise is a modern cloud-native application that supports easy deployment to your cloud static site host of choice.
 
 Simply fork [Arise on Github](https://github.com/spectrasecure/arise), edit your site, and point your cloud vendor to your repository. The included CI workflow does all the hard work of building and deploying your site straight from the cloud.
 
@@ -38,11 +38,11 @@ Arise websites may be spartan on the surface, but they are designed to take adva
 
 ## Practical pages for real-world use
 
-Real websites don't have just one page, but rather are built on top of hierarchies of linked pages filled with content. Arise builds websites that are designed to be modular and traversable.
+Most projects like this are one-off tech demos. While many of them "work", they often lack critical CMS-style features that are important for actually organising stuff on your website. Real websites don't have just one page, but rather are built on top of hierarchies of linked pages. 
 
-Arise supports the creation of dynamic index pages based on individual page metadata. Just tell Arise where you need an index, and it will build it for you all on its own.
+Arise solves this problem by building websites that are designed to be modular, hierarchical, and traversable. Arise supports the creation of dynamic index pages based on individual page metadata— just tell Arise where you need an index, and it will build it for you all on its own.
 
-For an example of what the index pages created by Arise look like, check out the [Sample Posts](posts) on this website.
+For an example of what index pages created by Arise look like, check out the [Sample Posts](posts) on this website.
 
 ## Get started with Arise
 

arise-source/posts/ci-xml-reserved-characters/index.md

@@ -0,0 +1,17 @@
+<!-- BEGIN ARISE ------------------------------
+Title:: "CI Test Suite - XML Reserved Characters & < > ' ""
+
+Author:: "Spectra Secure & < > ' ""
+Description:: "This post tests if we are properly filtering XML reserved characters in page metadata & < > ' ""
+Language:: "en"
+Thumbnail:: "kanagawa.jpg"
+Published Date:: "2023-11-08"
+Modified Date:: "2023011-08"
+
+---- END ARISE \\ DO NOT MODIFY THIS LINE ---->
+
+# CI Test Suite - XML Reserved Characters
+
+This page is part of a test suite to ensure that when a user tries to stick XML reserved characters into page metadata, such characters are properly converted to escape characters. This way we ensure that such characters don't break the monolithic sitemap or RSS feed.
+
+The way we do this is by having a test page in our template site which contains a post whose title, author, and destripction all contain the XML reserved characters (&<>'"). This test suite verifies that this output page has all of the reserved characters properly sanitised to the escape code versions, so that they're safe to handle within the site's XML sitemap and RSS feed.

arise-source/posts/ci-xml-reserved-characters/kanagawa.jpg

@@ -0,0 +1,73 @@
+#!/bin/bash
+testpage='arise-out/posts/ci-xml-reserved-characters/index.html'
+
+echo "Arise CI - XML Reserved Character Sanitisation"
+echo "=============================================="
+echo "This is a test suite to ensure that when a user tries to stick XML reserved characters into page metadata, such characters are properly converted to escape characters. This ensures that such characters don't break the monolithic sitemap or RSS feed."
+echo ""
+echo "The way we do this is by having a test page in our template site (""$testpage"") which contains a post whose title, author, and destripction all contain the XML reserved characters (&<>'"'"'"). This test suite verifies that the output page has all of the reserved characters properly sanitised to the escape code versions, so that they're safe to handle within the site's XML sitemap and RSS feed."
+echo ""
+echo ""
+
+echo "Testing to ensure the Arise site built the test suite page..."
+if [ -f $testpage ] 
+then
+        echo "SUCCESS!"
+else
+        echo "FAILED. No page was found where the test post is supposed to exist."
+        echo " - Check that you haven't moved the test post located in arise-source/posts somewhere else"
+        echo " - Check that you haven't broken Arise entirely"
+        echo "Good luck, choom!"
+        exit 1
+fi
+echo ""
+
+echo "Testing to ensure that the title is rendering as it should..."
+titletest="<title>CI Test Suite - XML Reserved Characters &#38; &#60; &#62; &#39; &#34;"
+if [[ $(grep "$titletest" $testpage) ]]
+then
+        echo "SUCCESS!"
+else
+        echo "FAILED. The page title we were looking for did not render properly."
+        echo ""
+        echo "Pattern we were trying to match:"
+        echo "$titletest"
+        echo "==========="
+        echo "Full line that contains a discrepancy:"
+        echo "$(grep '<title>' $testpage | head -1)"
+        exit 1
+fi
+echo ""
+
+echo "Testing to ensure that the author is rendering as they should..."
+authortest='<meta name="author" content="Spectra Secure &#38; &#60; &#62; &#39; &#34;">'
+if [[ $(grep "$authortest" $testpage) ]]
+then
+        echo "SUCCESS!"
+else
+        echo "FAILED. The page author line we were looking for did not render properly."
+        echo ""
+        echo "Pattern we were trying to match:"
+        echo "$authortest"
+        echo "==========="
+        echo "Full line that contains a discrepancy:"
+        echo "$(grep '<meta name="author"' $testpage | head -1)"
+        exit 1
+fi
+echo ""
+
+echo "Testing to ensure that the description is rendering as it should..."
+descriptiontest='<meta name="description" content="This post tests if we are properly filtering XML reserved characters in page metadata &#38; &#60; &#62; &#39; &#34;">'
+if [[ $(grep "$descriptiontest" $testpage) ]]
+then
+        echo "SUCCESS!"
+else
+        echo "FAILED. The page description line we were looking for did not render properly."
+        echo ""
+        echo "Pattern we were trying to match:"
+        echo "$descriptiontest"
+        echo "==========="
+        echo "Full line that contains a discrepancy:"
+        echo "$(grep '<meta name="description"' $testpage | head -1)"
+        exit 1
+fi