DEV Community: mkt

Regular Expressions for Non-Programmers.

mkt — Sat, 24 Jul 2021 10:21:43 +0000

Useful knowledge when working with long texts.

This article is for those who don’t want to become an expert but get the maximum reward with minimum effort. The internet is full of tutorials on the topic and there are already lots of really good resources. I will list some of them at the bottom. The “problem” I see is that they are mostly not really targeted at non-technical users. They try to explain everything in one article. You read the first few paragraphs and think: “Well… Some other day, maybe.”

The goal of this article is that you can easily read it to the end, understand everything and go on with your life with an actual productivity gain. I will only cover a few handy things. Regular expressions can be very useful for anyone who is working with texts a lot and most editors support them, like all the popular office suites. I will use Google Docs for the examples in this article.

A Special Character

Everything behaves normally until we enable regular expressions. Suddenly not only the term “dog.” (with a dot at the end) is matched but also the first one, where there is no dot but a space. That’s because the dot has a special meaning in a regular expression. It’s like a placeholder that simply matches any character, even spaces and… yes, dots. Here’s another example:

In the end, we search for any combination of three characters of which the last one is a “t”. Note how it also matches “ght” in “caught” and even “ It” because of the space character it starts with.

This alone can already be quite useful in some situations but it certainly has its drawbacks. Most times, matching “anything” is not really what you want.

Other Special Characters

If you compare it to the dot and how it’s a placeholder for simply any character, you can say character sets are “custom placeholders” for only a few selected characters.

This whole [fcr] thing is now a placeholder for either an “f”, a “c” or an “r”. Combined with the “at” after it, this expression only matches exactly the three words “fat”, “cat” and “rat”. But, as you can see, also as part of other words. You will learn how to avoid that in a moment.

You can also define ranges of characters. To create a placeholder for any letter in the alphabet, you don’t need to write [abcdefghijklmnopqrstuvwxyz]. You can simply write [a-z]. For numbers it’s [0-9] and you can even combine them easily. [a-z0-9] is a placeholder for all letters and numbers and
[b-f1-6] is one for all letters from b to f and numbers from 1 to 6.

Oh, and… In the first screenshot of this article, you see how “Match case” isn’t enabled. Otherwise, [a-z] and [A-Z] wouldn’t be the same. And in that case, don’t try things like [A-z]. It doesn’t do what you might hope for. But you can use [a-zA-Z]… or just check that box.

I guess this last example makes it very clear what regular expressions are all about. You aren’t bound to exact words or phrases. You can search a text for complex patterns. And this example also demonstrates how powerful that can be. How else would you search for… times?

? * + (optional/repeating characters/placeholders)

Sorry? Oh, yes. Sure. Just put a question mark after that first placeholder, to make the leading “0" optional while the hour is less than 10.

Like asking yourself: “Is this really here… question mark”

Those parenthesis? Good catch. You can group stuff together so that the question mark applies to it as a whole.

Also handy: The plus sign and the star. [0-9]+ or [a-z]*
You can search for something that is there “at least one time” (plus) or “any number of times or not at all” (star). And if that is not enough, you can use { and } to say “two to four times”: [0-9]{2,4} or “at least three times”:
[a-z]{3,}.

\b (word boundary)

Now back to the “also as part of other words” problem.

The \b “helper” doesn’t really match any characters. It means “word ends here” or “word starts here”, depending on where you put it. If you put it on both sides, that means you are looking for a “whole word”.

Problem solved.

| (this or that)

The pipe character simply means “or”. You can basically search for multiple things at the same time.

Your “search options” can be as simple as single characters, like a|b, or more complex expressions. Let’s combine a few things here.

\ (escaping)

One last thing. So, there are special characters with a special meaning. By the way, these are all of them: .+*?()[{^$|\ That means you can’t just search for them literally. To do that you have to put a backslash in front of them. With that, we can fix the issue from the first example.

The end.

We will stop here. I want this article to be “digestible” but that’s a lot of handy stuff already I believe. You can search for whole words only or for words that start or end with something or for multiple words, alternative/common (mis)spellings, patterns like time and date and more. If you want to explore the rabbit hole a bit more, there are some useful resources below.

Other Resources

regextester.com and regex101.com

Awesome tools to build your own, more complex regular expressions. When hovering the expression field, it shows you what exactly is happening. They both also have a library of commonly used regular expressions which you can explore and try to make sense of.

regular-expressions.info/quickstart.html

Best quick start guide and cheat sheet but the visual style already scares you away. No need for regular expressions. Well… functional though.

https://www.youtube.com/watch?v=M7vDtxaD7ZU

Great talk. Requires some experience follow along.

Make GitHub Workflows run consecutively

mkt — Fri, 16 Jul 2021 19:19:52 +0000

TLDR: https://github.com/marketplace/actions/consecutive-workflow-action

This article assumes some basic experience with GitHub Actions/Workflows.

When you work with GitHub Actions, you have almost infinite flexibility at your disposal and you can do almost anything. But sometimes you have to be a bit creative to achieve what you want.

Within a workflow, jobs are executed in parallel but you can create dependencies between jobs so that they run consecutively. Steps within a job always run one after another.

Workflows themselves always run independently of each other. You can trigger the same workflow multiple times and there will be multiple parallel runs. That’s perfectly fine in many common scenarios. When there are two new pull requests, submitted at almost the same time, your automated tests can run for both pull requests at the same time.

But there are situations where this actually leads to problems. I like to make my workflows not just perform some checks but actually update the repository. I use a repository kind of as a database. Automatically fixing code formatting issues is probably a more relatable use case. :D

The problem now with parallelism is of course this:

Updates were rejected because the remote contains work that you do not have locally.
This is usually caused by another repository pushing to the same ref.You may want to first integrate the remote changes (e.g., 'git pull ...') before pushing again.
See the 'Note about fast-forwards' in 'git push --help' for details.

Two workflow runs pushing to the same repository at almost the same time will most likely fail. Pulling changes right before pushing is the first thing that comes to mind but that can lead to merge conflicts that your workflow will not be able to resolve on its own.

So you need to make sure that workflow run B only clones the repository once workflow run A is done with pushing. They need to run consecutively. GitHub does not offer that out of the box but a sufficiently comprehensive API to implement it yourself. I’ll not cover the implementation in detail but this is the general, fairly simple idea:

As I mentioned before, you can create dependencies between jobs within a workflow. So the first job of the workflow is simply to look at its previous run and wait for it to complete. I don’t care about its result, whether it failed or succeeded or whatever, I just want to make sure it’s not running anymore. As long as that’s not the case, wait a bit and then check again. So there’s a nice little while loop involved to make sure this first job in our workflow blocks the rest of it until the previous run is completed.

I just published this as a GitHub Action that is super easy to use, in case I’m not the only one with the problem.

jobs:
  consecutiveness:
    runs-on: ubuntu-latest
    steps:
    - uses: mktcode/consecutive-workflow-action@v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}

  # your other jobs
  something:
    runs-on: ubuntu-latest
    needs: [ consecutiveness ]
    steps:
    # ...

One word about the GITHUB_TOKEN... The token is needed to avoid rate limitation issues when performing API calls. Make sure you read the security note in the repository’s Readme.

That’s it! Hope its useful for some. If you leave a like for the article you make me feel more comfortable about writing articles like this. Follow me on GitHub if you are interested in what I’m working on. Thanks for reading! :)

Multiple Environments With GitHub Pages

mkt — Fri, 25 Jun 2021 21:05:46 +0000

or... When you’re working on a static site and GitHub Pages feels like the perfect hosting solution, since you like having everything in one place and then you realize you need an additional environment but you still don’t want to use anything but GitHub… Here’s what you can do.

This is a “special needs” article but also a general introduction to GitHub Actions.

Since the advent of Single Page Applications the requirements for hosting have been reduced to a minimum. Anything that can serve a static HTML file will do the job just fine and the browser, bombarded with Javascript, does the heavy lifting. High availability and security is a totally different topic of course but in this case I believe GitHub has you covered.

With Pages GitHub offers a very convenient service for hosting such an app. You push to your repository and GitHub updates the deployment for you. You even get a nice subdomain like username.github.io or you can connect your own domain. There’s just one downside.

If your project is not just a literally very static website but an actual “app” and you are working together with other people, you probably want to have multiple deployments, like a development and a staging environment. The problem is… A repository on GitHub can only have a single GitHub Page instance and you probably don’t want to maintain a mirror repository for each of your environments, so you’ll end up using an external hosting service and then you start questioning GitHub Pages as your preferred hosting solution all together. In this article I will show you what I did to “stay on GitHub“.

GitHub Actions & Workflows

Not only does GitHub offer free hosting but also free and pretty flexible and powerful workflow automation with GitHub Actions. If you are not already familiar with CI/CD and GitHub Actions in particular, I recommend you to change that asap. I ignored this topic for far too long but now I’m a huge fan. It simply gives you superpowers.

I’ll try to give you a brief but effective introduction:

GitHub runs virtual machines that act as task runners for your projects. Those tasks can either run on a schedule, as a cronjob, or get triggered by events that occur on GitHub, like pushing commits to a branch, opening or closing issues or commenting on them, to name some common ones. These tasks can be comprised of multiple steps that can be chained together and depend on one another, hence the term Workflows. The terminology is the following: Workflows have one or more jobs, each with one or more steps, which can make use of an action, which can have inputs and outputs.

Actions are the “atoms” a workflow is made of, so to say. An action is a repository on GitHub, containing an action.yml file, describing its inputs and outputs. That means an action can basically do anything you want. It is worth mentioning though, that you actually don’t even have to use actions in your workflows at all. You can also just run arbitrary commands on the operating system the workflow runs on and sometimes that is all you need. You can think of GitHub Workflows simply as… “executing stuff” on a virtual machine that GitHub spawns for you on demand.

To add a new workflow you need to add a YAML configuration file inside the .github/workflows directory of your repository. GitHub will automatically pick that up and run it according to the terms you configure. Here’s a hello-world.yml that shows probably the most simple and useless workflow possible:

name: Hello World  
on:  
  schedule:  
    - cron: '0 0 * * *'  
jobs:  
  hello-world:  
    runs-on: ubuntu-latest  
    steps:  
      - run: echo Hello World!

(I’ll not cover the YAML format in this article but I’ll tell you that the dashes represent items in an array and if there are no dashes you are dealing with object keys. If there are dashes followed by… no dashes… it’s an array of objects. In contrast to plain JSON it supports single quotes and comments. Everything that is not quoted is considered a string, unless it’s obviously not a string. YAML is a superset of JSON. Wait… Did I just… anyway…)

Once a day at 0:00 o’clock this workflow runs and prints “Hello World!” to some virtual Ubuntu machine’s stdout, somewhere in GitHub’s networks. It does not use any action but instead runs an echo command. A single step can either run commands OR use an action.

jobs:  
  hello-world:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: hello-world/say-action@v1  
        with:  
          say: Hello World!

You set the inputs of an action, if it has any, by using the with keyword. I’d have called it inputs but who cares.

Outputs and Dependent Jobs

If an action has outputs, you can use them in consecutive steps of the same job. The step with the outputs just needs an id to be referenced by other steps.

jobs:  
  hello-world:  
    runs-on: ubuntu-latest  
    steps:  
      - id: get-name  
        uses: hello-world/get-name-action@v1 # has a "name" output  
      - uses: hello-world/greet-action@v1          
        with:  
          name: ${{ steps.get-name.outputs.name }}

To make a job dependent on a previous one and thus allow it to use its outputs, you must specify which outputs exactly to make available and then you define an array of “needs”.

jobs:  
  get-name:  
    runs-on: ubuntu-latest  
    outputs:  
      name: ${{ steps.get-name.outputs.name }}  
    steps:  
      - id: get-name  
        uses: hello-world/get-name-action@v1 # has a "name" output

  say-name:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: hello-world/greet-action@v1          
        with:  
          name: ${{ steps.get-name.outputs.name }}

Secrets & Environments

Sometimes you need to use credentials, like an API key and you don’t want to expose such values in your workflow file directly. In your repository’s settings you’ll find a section called “Secrets”.

Here you can define those values and you can use them in your workflows like this.

steps:  
  - run: echo ${{ secrets.SECRET_STRING }}

Secrets can also be defined for an entire organization on GitHub (go to its settings and there “Secrets”), to be available in all workflows across all repositories of that organization. On the other hand, you can also further restrict access to secrets. That’s what environments are for. Think of them as “categories” of secrets in a certain repository.

You can tell a workflow job what environment’s secrets it can access. Let’s say you’ve created an environment in your repository’s settings called development.

jobs:  
  hello-world:  
    runs-on: ubuntu-latest  
    environment: development  
    steps:  
      - run: echo ${{ secrets.DEVELOPMENT_ENV_SECRET }}

In the environment settings you’ll see that access can also be restricted to certain branches, so that only a workflow that was triggered by an event related to a matching branch has access to the environment’s secrets and you can also require an admin to approve those workflow runs before they actually run.

We’ll use that later in the article.

After digesting this very condensed information you should have a feeling for how powerful and flexible these workflows can be and that you can basically do anything you can imagine. For example, I am using them to integrate cryptocurrency payments into deployment pipelines on GitHub but that’s a top secret project and you better erase that information from your memory right now. Ok? Good. Thanks.

If you want to dive deeper into GitHub Actions on your own, browse through the docs and if you want to start experimenting, I recommend adding Workflow syntax for GitHub Actions and Events that trigger workflows to your bookmarks.

ATTENTION: A quick note on security when using secrets with unofficial/unverified actions!

As mentioned, actions can take inputs. Those inputs can be secrets. A common example is Docker:

jobs:  
  build-and-push-docker-image:  
    runs-on: ubuntu-latest  
    steps:  
      - name: Login to DockerHub  
        uses: docker/login-action@v1   
        with:  
          username: ${{ secrets.DOCKERHUB_USERNAME }}  
          password: ${{ secrets.DOCKERHUB_TOKEN }}

The action being used here is docker/login-action, which is a verified action:

What version of the action you use is specified by the @v1 at the end, which is a branch or tag name. Now, Docker might be a trustworthy author but even trusted organizations might have a new team member every now and then and sometimes new team members turn out to be not as trustworthy as the rest of the organization they just joined and security policies are sometimes more a theoretical thing. Anyway… At the latest when working with unverified actions you need to be aware of one thing (in case you aren’t already):

The code referenced by a tag can change!

That means: An action you pass one of your secrets to, can today be your best friend and tomorrow steal your most secret secrets, without you ever even knowing, and reveal them to your worst enemies, who are browsing the dark web looking for the latest hacks and leaks!

If in any doubt, reference an action by a commit hash, like this:

- name: Login to shady service  
  uses: trustme/spy-action@`172239021f7ba04fe7327647b213799853a9eb89`  
  with:  
    password: ${{ secrets.SUPER_SECURE_PASSWORD }}

AND make sure that the code referenced by that commit hash actually does what the readme says it does. If you don’t… well… then just use the tag name. You have been warned (by the docs too).

My GitHub Pages Scenario

Now that you should be up to speed with GitHub Actions and Workflows and everything, I’ll finally go into my specific real-world-scenario where a few workflows manage multiple GitHub Pages instances, representing different environments for the app I was working on.

I needed three environments that behave like this:

Production: The app that users will actually use. Updated on push to main branch, requiring admin approval.
Development: Preview of the latest development progress. Updated on push to development branch.
Staging: “Phoenix” deployments, created for pull requests from feature branches and deleted on close, which includes merges.

The main repository, just called “app”, does not have it’s own GitHub Page. Instead there are two additional repositories, “app-prod” and “app-dev”. I mentioned in the beginning, that you surely don’t want to maintain any mirror repositories and that’s why these repositories only hold a build of the app and have their GitHub Page enabled. That’s their only purpose. Additionally each pull request on the development branch will result in a new repository named “app-pr-”. Here’s a visualization:

Workflow: Development Build and Deploy

Let’s start with the development deployment, since it’s the most straight forward without any extras. Take a look at this workflow file and then I’ll guide you through it step by step. The gist of what happens is, we checkout the repository, build the app and push that build to the app-dev repository.

1.) The workflow runs when new commits are pushed to the development branch but not for changes that only affect the workflow files themselves or any markdown files:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L2-L7

2.) We set the URL that is connected to the app-dev repository’s GitHub Page as a global environment variable, to use it later in the workflow:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L8-L9

3.) There’s actually just one job, with a lot of steps, that runs on a ubuntu-latest virtual machine, using secrets we configured for our development environment in the repository settings:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L11-L16

FYI: Setting the url key for the environment only means that GitHub will show a link to that URL in different places on github.com, like in a related pull request or the repository’s deployments overview.

4.) We use an official action (actions provided by the actions GitHub organization) to prepare Node.js on the VM:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L18-L19

5.) We use normal Git commands to set the GitHub Actions bot as the commit author, because later we will commit and push changes to a repository:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L22-L25

6.) We checkout the repository to a build directory, using the official checkout action:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L27-L30

FYI: If you don’t pass a specific repository name to the checkout action, like in step 8, it will simply checkout the repository in which the workflow lives.

7.) We move into this build directory and actually build the app (a Nuxt.js app by the way), after setting some environment variables. Then we move back to the parent directory:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L32-L41

FYI: Exported environment variables are not persistent across jobs/steps and are not to be confused with the workflow’s env vars (line 9), which are available throughout the entire workflow.

8.) Now we checkout the app-dev repository to a deploy directory, this time also providing a personal access token as a secret. This allows as to push changes to that repository in the next step:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L43-L48

9.) And then we simply copy the files from the build directory to the deploy directory, resulting in changes in the repository that we then need to commit and push:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-dev.yml#L50-L58

FYI: Line 54 and 55 add files needed for the GitHub Page to work properly. We disable Jekyll as GitHub’s default static site generator (we take care of that ourselves by using Nuxt) and we configure the domain we want to be connected to our development deployment.

Done!

Now isn’t that super easy and intuitive? :D I’m not claiming that this is the smartest and most efficient way of doing this. But I hope it’s comprehensible enough. Let’s move on to the production deployment.

Workflow: Production Build and Deploy

Take a look at the workflow file and you will notice that it’s… pretty much the same. The only differences are the branch this workflow “listens” to, the deployment URL, the environment, two of the env vars used when building the app and the deployment repository. The more significant difference however, is the environment’s configuration in the repository settings. It will allow this workflow to run only after an admin approved it.

And I think that’s all there is to say about the production deployment and we can take a look at the most interesting part of all this. Pull requests.

Workflow: Pull Request Build and Deploy

Again, first go through the workflow file, try to make sense of it on your own and then I’ll just explain what’s different here.

Most importantly there is no repository for this deployment yet. We have to create it from our workflow. To have a unique name for the repository, we fetch the GraphQL ID of the pull request:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-pr.yml#L9-L10

FYI: The github variable lets you access the context of a workflow run, e.g. the event that triggered it, including the pull request object itself.

There’s a separate job that creates the repository, using a special action I created:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-pr.yml#L13-L21

You can take a look at the action itself, to see what’s actually going on:

https://github.com/mktcode/create-repository-action/blob/b1dd3b3dcdcc491795ae189db97383a47f04808e/index.js#L6-L29

The next job depends on the repository being created and uses the pr-staging environment:

https://github.com/OpenQDev/app/blob/715573cd6ceebe87e7e235180510eaacacb7d74a/.github/workflows/deploy-pr.yml#L23-L28

From there on it’s pretty much the same as the development and production workflow. The only thing missing is deleting the repository, once the pull request gets merged/closed. This is handled in a separate workflow. It uses another special action I created.

An now you can have pull requests like this one with their own automatic deployments to test the changed before merging.

And that’s actually it! We’re done. We now have a static site project, with multiple environments, living entirely on GitHub. And this is just one possible configuration of which I’m sure is far from perfect. In fact I am working on some improvements. So maybe I will update this article soon. But I hope you got a feeling for what’s possible with GitHub Actions and Workflows and that you start experimenting and creating your own ones for your own individual purposes now.

Thanks for reading!

You can follow me on Twitter and GitHub. For longer discussions, questions, feedback and so on, I just created a Discord Server. Not sure if that really makes sense but feel free to step by and say hello. :)

GitHub Pages with Dynamic Routes

mkt — Fri, 18 Jun 2021 10:29:05 +0000

The problem covered in this article has been discussed for some time now: https://github.com/isaacs/github/issues/408 Unfortunately there’s still no real solution and a workaround is needed.

GitHub Pages is a super convenient hosting service for static sites, e.g. a personal portfolio or blog or a project’s documentation and even modern web apps are in many cases not much more than a static HTML file and (a lot of) Javascript. But static sites come with the downside of... well... being static. That means you can’t have dynamic routes, like your-project.github.io/posts/<post-slug> where <post-slug> is a dynamic parameter. All possible routes need to be known in advance and point to a static file. Maybe those files are generated by some build process and whenever you add a new blog post, you just re-deploy the page. Using CI/CD pipelines like GitHub Actions/Workflows, that process might even boil down to pushing a new markdown file to your repository and that is sufficiently convenient for a lot of scenarios. But sometimes it’s not and you just need dynamic paths, especially when user generated content is involved or a project becomes more complex.

How do dynamic routes even work?

If you are well familiar with the concept and you just want to know how to trick GitHub Pages into supporting dynamic routes, you can skip this part and continue with The Solution.

A route/path is traditionally pointing to a (static) file on the server that is represented by a domain.

your-server.com/some/path/index.html

If you try to access a file that does not exist on that server, it will respond with an error, which usually means it will serve you a default 404.html that comes with the server. You’ve probably seen something like this:

That’s such a default error file, in this case served by an nginx server. However, you can configure a server in a way that it serves you a certain resource/file, no matter what path you request. Let’s say you have an index.html on the server and you configured it accordingly. You can now call your-server.com/index.html but also your-server.com/some/path/that/does-not-exist.html. It will always return the same index.html file. Now, that file can also be a script instead of just some static HTML file. Otherwise your dynamic routes wouldn’t be that dynamic since they all serve exactly the same content.

A front controller is such a dynamic script that handles all requests to your server and serves content dynamically, e.g. by fetching data from a database, based on what the actual request was, and then generating an HTML response from a template. This way you can support routes with dynamic parts, that you don’t have to know in advance, like the /posts/<post-slug> example from above.
GitHub Pages

GitHub Pages does not support such a front controller because it is not meant to serve dynamic content. Sure. You can use Javascript in your static HTML files to change its content dynamically, e.g. based on user interaction, and most web apps, as mentioned before, are nothing more than a static HTML file and then Javascript takes over from there. But all this happens in your browser and not on GitHub’s servers. So if you call your-username.github.io/some/file.html it will look for exactly that file and nothing else and if it can’t find it, because you didn’t add it to your repository, it will show you this:

That is GitHub’s default 404.html file. At this point I assume that most developers/users would now simply accept the bitter reality that GitHub Pages might not be the right service for them and instead move on to a more comprehensive hosting solution, where they have more control over what the server actually does behind the scenes. But not me! I’m a lazy minimalist and one platform account must be enough!

An old-fashioned alternative

At first I considered just being fine with a compromise and instead of having “real” dynamic routes, I could go back in the history of single page apps and use the # method, like the old AngularJS. In case you ever wondered, the part after the # is not really part of the actual URL a server responds to. It is just used by the browser to jump to an HTML anchor and you can access it in Javascript. The server does not even know about this part. It’s client-side only. But that means you can have routes that look like this:

your-server.com/#/posts/<post-id>

The app lives at / on the server and processes the part after # when running in the browser. When clicking a link in your app, it just updates the part after # and changes the content accordingly via Javascript. But that doesn’t look that nice and modern frameworks, like Next.js do not even support this form of routing anymore. Vue’s Nuxt.js actually has a fallback option but still...

The Solution

You already saw part of the solution in this post. It’s the 404 page. GitHub Pages actually allows you to add a custom 404.html to your repository, to adjust it to your project’s branding and so on. If you are familiar with the front controller pattern, you might have an “aahhhhhaaaa” moment now. The important part of this pattern is that it just takes any request and routes it to your app where the request is then handled. Well.. a 404 page is not much different. It handles aaaaall requests... that do not match any existing resource. You know where I am going with this? It is a bit different though. A classical front controller lives on the server and sends the desired response back to you as if the resource you requested actually exists physically. Tricking GitHub Pages into supporting dynamic routes is a bit more... tricky. Because it simply doesn’t! But we can make it look as if it does. The average human eye won’t notice the difference and it even works with the dynamic routing features of modern frameworks like Vue’s Nuxt.js or React’s Next.js.

Proof of concept

The simple trick is to let your custom 404.html redirect any request back to your app and then your app uses the browser history API to update the URL that your browser shows, to whatever was requested originally. You need to pass that information to your app when redirecting. For that I use... guess what?... our old friend, the #. I have a GitHub page set up here: https://mktcode.github.io/static-dynamic-routing and its 404.html looks like this:

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body></body>
  <script>
    window.location.href = '/static-dynamic-routing/#' + window.location.pathname.replace('/static-dynamic-routing', '')
  </script>
</html>

So instead of showing some 404 Not found! message, it just redirects you to the root path where the app lives. Note that this GitHub Page example lives in the subdirectory /static-dynamic-routing/ which is normal, when you set up a GitHub page for a repository. It will live under <your-username>.github.io/<repo-name>/. That’s why we have to do some replacements here. Otherwise we’d redirect the user to mktcode.github.io/. Fortunately you can configure a custom domain for your GitHub Page very easily and then you don’t have to take care of this.

So now, no matter what route we call, we’ll end up at our app and it will know about that route, so it can act accordingly. In my little example I do not much more than replacing the displayed URL in the address bar and manipulating some content. That’s basically how dynamic routing works in those modern frameworks.

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <h1>My App</h1>
    <h2 id="header">Post Path: {PATH}</h2>
  </body>
  <script>
    if (window.location.hash.length > 1) {
      const path = window.location.hash.replace('#', '')
      history.pushState({ page: 1 }, "Some title", '/static-dynamic-routing' + path)

      document.getElementById('header').innerHTML = document.getElementById('header').innerHTML.replace('{PATH}', path)
    }
  </script>
</html>

Try opening this link in your browser: https://mktcode.github.io/static-dynamic-routing/posts/my-post

For a split second you can see the # in your browser’s address bar. That’s when the redirect happens and then we pretend it never did happen. And that’s basically all there is to it.

Use with Nuxt.js

If you are more the react type of person, you’ll have to implement that on your own. I’ll only show the Nuxt.js way.

In Nuxt.js you can easily configure dynamic routes by just creating a file like /pages/posts/_slug.vue. Nuxt will do the rest and you have routes like /posts/my-post-title. This even works in static site mode but only if the site is delivered by the integrated Nuxt server or any other server configured in the same way (think: front controller pattern). With GitHub Pages this does not work and you’ll just see the 404 page. But here’s the proof that my approach works totally fine even with Nuxt.js:

https://mktcode.github.io/dynamic-nuxt-gh-pages/post/my-totally-dynamic-post-title

All it needs is the 404.html file in the static directory and a router middleware, which performs a nuxt-internal redirect to the original route, resulting in the address bar of your browser being updated. If that route does not exist in your application, the Nuxt error page shows. By the way... It now uses #! for the redirect, to still allow normal HTML anchors. Everything that worked before should still work, plus... dynamic routes for GitHub Pages! Well... kind of. :)

The End

Hope you enjoyed my first ever article! :) Follow me on Twitter and GitHub and comment and bla bla bla. There’s more to come! Five years later... “Hey I think I’ll start writing dev articles!” :D