Generate a Pull request for static content using a simple HTML form

Jamstack has been in the website world for years. Static Site Generators (SSGs) – which often have content that lives right in a GitHub repo itself – are a big part of that story. It opens up the idea of ​​having contributors who can open pull requests to add, modify, or edit content. Very useful!

Examples of this are as:

Why build with a static website access?

When we need to build content-based pages like this, it is common to think about which database we should use. Storing content in a database is a well-established idea. But that is not the only approach! SSGs can be a good alternative because …

  • They are cheap and easy to install. SSGs are usually free, which makes them great for an MVP or a proof of concept.
  • They have great security. There is nothing to hack through the browser as everything the page contains is often just static files.
  • You are ready to scale. The host you’re already on can handle it.

There is another benefit to us when it comes to a content site. The content of the page itself can be written in static files right in the repo. This means that adding and updating content can be done 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 open source concept that allows for community contributions.

But let’s go the super lo-fi route and embrace the idea of ​​pull requests for content, without using more than basic HTML.

The challenge

How people contribute to adding or updating a resource is not always entirely straightforward. People need to understand how to distribute your inventory, how and where to add their content, content formatting standards, mandatory fields and all sorts of things. They may even need to “spin up” the site locally to make sure the content looks right.

People there seriously want to help our site will sometimes withdraw because the process of contributing is a technological hurdle and learning curve – which is sad.

Do you know what anyone can do? The use <form>

Like a normal website, the easy way for people to submit content is to fill out a form and submit it with the content they want.

What if we could create a way for users to contribute content to our sites using nothing but HTML <form> designed to take exactly the content we need? But instead of sending the form to a database, does it go as a pull request towards our static site generator? There’s 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 warehouse by adding query parameters to a special GitHub URL. This comes straight from the GitHub documents themselves.

Conversely, let us construct this.

If we know we can pre-fill a link, then we have to generate the connection. We try to make it easy to remember. To generate this dynamic data-filled link, we 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 splitting the repo on GitHub and adding a new Markdown file. But let’s see how we can do that with a mold instead of jumping through those hangers.

The serverless site itself has many categories (such as for forms) that 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 the resource files are in this folder in the archive.

Displays the main page of CSS-Tricks Serverless repo in GitHub, shows all the files.

Just select 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.

If we look at this content, our form should have these columns:

  • Title
  • URL
  • Author
  • Tags
  • Excerpt or description of the link.

So let’s build an HTML form for all these 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 use Bulma for styling, so the class names used here are from it.

We are now writing a JavaScript function that transforms a user’s input into a friendly URL, which we can combine as GitHub query parameters at our pull request. Here are step by step:

  • Get user input on the content they want to add
  • Generate a string from all that content
  • Encode the string to format it in a way that people can read
  • Attach the encoded string to a complete URL pointing to the GitHub page for new pull requests

Here is the pen:

After pressing the Submit button, the user is taken directly to GitHub with an open pull request for this new file in the correct location.

GitHub pull request screen that displays a new file of content.

Quick Warning: Users still need a GitHub account to contribute. But this is still a lot easier than having to know how to distribute a repo and make a pull request from that fork.

Other benefits of this approach

Well, first of all, this is a form that can be found on our site. We can style it the way we want. That kind of control is always nice to have.

Second, since we have already written JavaScript, we can use the same basic idea to talk to other services or APIs to process the input first. For example, if we need information from a website (such as the title, meta description, or favicon), we may retrieve that information simply by entering the URL.

To take things further

Let’s play with the second point above. We could simply fill out our form in advance by retrieving information from the URL provided to the user, instead of having them enter it by hand.

With that in mind, now let’s only ask the user thaw input (instead of four) – only the URL and tags.

How does it work? We can fetch Metadata from a JavaScript-enabled site simply by having the URL. There are many APIs that retrieve information from a website, but you may be the one I built for this project. Try clicking any URL like this:

https://metadata-api.vercel.app/api?url=https://css-tricks.com

The demo above uses it as an API to pre-fill data based on the URL entered by the user. Easier for the user!

Finishes

You could think of this as a very minimal CMS for any kind of static site generator. All you have to do is customize the form and update the pre-filled query parameters to match the data formats you need.

How are you going to use that kind of thing? The four places we saw in the beginning are good examples. But there are so many other times when it may be necessary to do something with a user submission, and this can be a low-key way to do it.

Leave a Comment