Jamstack has been in the website world for years. Static Site Generators (SSGs) — which often have content that lives right within a GitHub repo itself — are a big part of that story. That opens up the idea of having contributors that can open pull requests to add, change, or edit content. Very useful!
Examples of this are like:
- CSS-Tricks’ Serverless Site (repo)
- CSS-Tricks’ Coding Fonts Site (repo)
- Jamstack’s Site Generator Site (repo)
- My own Free Developer Stuff Site (repo)
Why built with a static site approach?
When we need to build content-based sites like this, it’s common to think about what database to use. Keeping content in a database is a time-honored good idea. But it’s not the only approach! SSGs can be a great alternative because…
- They are cheap and easy to deploy. SSGs are usually free, making them great for an MVP or a proof of concept.
- They have great security. There is nothing to hack through the browser, as all the site contains is often just static files.
- You’re ready to scale. The host you’re already on can handle it.
There is another advantage for us when it comes to a content site. The content of the site itself can be written in static files right in the repo. That means that adding and updating content can happen right from pull requests on GitHub, for example. Even for the non-technically inclined, it opens the door to things like Netlify CMS and the concept of open authoring, allowing for community contributions.
But let’s go the super lo-fi route and embrace the idea of pull requests for content, using nothing more than basic HTML.
The challenge
How people contribute adding or updating a resource isn’t always perfectly straightforward. People need to understand how to fork your repository, how to and where to add their content, content formatting standards, required fields, and all sorts of stuff. They might even need to “spin up” the site themselves locally to ensure the content looks right.
People who seriously want to help our site sometimes will back off because the process of contributing is a technological hurdle and learning curve — which is sad.
You know what anybody can do? Use a <form>
Just like a normal website, the easy way for people to submit a content is to fill out a form and submit it with the content they want.
What if we can make a way for users to contribute content to our sites by way of nothing more than an HTML <form> designed to take exactly the content we need? But instead of the form posting to a database, it goes the route of a pull request against our static site generator? There is a trick!
The trick: Create a GitHub pull request with query parameters
Here’s a little known trick: We can pre-fill a pull request against our repository by adding query parameter to a special GitHub URL. This comes right from the GitHub docs themselves.
Let’s reverse engineer this.
If we know we can pre-fill a link, then we need to generate the link. We’re trying to make this easy remember. To generate this dynamic data-filled link, we’ll use a touch of JavaScript.
So now, how do we generate this link after the user submits the form?
Demo time!
Let’s take the Serverless site from CSS-Tricks as an example. Currently, the only way to add a new resource is by forking the repo on GitHub and adding a new Markdown file. But let’s see how we can do it with a form instead of jumping through those hoops.
The Serverless site itself has many categories (e.g. for forms) we can contribute to. For the sake of simplicity, let’s focus on the “Resources” category. People can add articles about things related to Serverless or Jamstack from there.
All of the resource files are in this folder in the repo.
Just picking a random file from there to explore the structure…
---
title: "How to deploy a custom domain with the Amplify Console"
url: "https://read.acloud.guru/how-to-deploy-a-custom-domain-with-the-amplify-console-a884b6a3c0fc"
author: "Nader Dabit"
tags: ["hosting", "amplify"]
---
In this tutorial, we’ll learn how to add a custom domain to an Amplify Console deployment in just a couple of minutes.Looking over that content, our form must have these columns:
- Title
- URL
- Author
- Tags
- Snippet or description of the link.
So let’s build an HTML form for all those fields:
<div class="columns container my-2">
<div class="column is-half is-offset-one-quarter">
<h1 class="title">Contribute to Serverless Resources</h1>
<div class="field">
<label class="label" for="title">Title</label>
<div class="control">
<input id="title" name="title" class="input" type="text">
</div>
</div>
<div class="field">
<label class="label" for="url">URL</label>
<div class="control">
<input id="url" name="url" class="input" type="url">
</div>
</div>
<div class="field">
<label class="label" for="author">Author</label>
<div class="control">
<input id="author" class="input" type="text" name="author">
</div>
</div>
<div class="field">
<label class="label" for="tags">Tags (comma separated)</label>
<div class="control">
<input id="tags" class="input" type="text" name="tags">
</div>
</div>
<div class="field">
<label class="label" for="description">Description</label>
<div class="control">
<textarea id="description" class="textarea" name="description"></textarea>
</div>
</div>
<!-- Prepare the JavaScript function for later -->
<div class="control">
<button onclick="validateSubmission();" class="button is-link is-fullwidth">Submit</button>
</div>
</div>
</div>I’m using Bulma for styling, so the class names in use here are from that.
Now we write a JavaScript function that transforms a user’s input into a friendly URL that we can combine as GitHub query parameters on our pull request. Here is the step by step:
- Get the user’s input about the content they want to add
- Generate a string from all that content
- Encode the string to format it in a way that humans can read
- Attach the encoded string to a complete URL pointing to GitHub’s page for new pull requests
Here is the Pen:
After pressing the Submit button, the user is taken right to GitHub with an open pull request for this new file in the right location.
Quick caveat: Users still need a GitHub account to contribute. But this is still much easier than having to know how to fork a repo and create a pull request from that fork.
Other benefits of this approach
Well, for one, this is a form that lives on our site. We can style it however we want. That sort of control is always nice to have.
Secondly, since we’ve already written the JavaScript, we can use the same basic idea to talk with other services or APIs in order to process the input first. For example, if we need information from a website (like the title, meta description, or favicon) we can fetch this information just by providing the URL.
Taking things further
Let’s have a play with that second point above. We could simply pre-fill our form by fetching information from the URL provided for the user rather than having them have to enter it by hand.
With that in mind, let’s now only ask the user for two inputs (rather than four) — just the URL and tags.
How does this work? We can fetch meta information from a website with JavaScript just by having the URL. There are many APIs that fetch information from a website, but you might the one that I built for this project. Try hitting any URL like this:
https://metadata-api.vercel.app/api?url=https://css-tricks.com
The demo above uses that as an API to pre-fill data based on the URL the user provides. Easier for the user!
Wrapping up
You could think of this as a very minimal CMS for any kind of Static Site Generator. All you need to do is customize the form and update the pre-filled query parameters to match the data formats you need.
How will you use this sort of thing? The four sites we saw at the very beginning are good examples. But there are so many other times where might need to do something with a user submission, and this might be a low-lift way to do it.
If I want to make pull request in organization repo it doesn’t want to work. Please advise