I am working on a base template which acts as a seed for all of my micro tools which run 100% on Github. I have a number of little micro tools I want to build, and I needed a series of core building blocks that I could fork and reuse across all my tools. I produced this base template, and next up was creating a simple YAML editor, that would allow me to edit the YAML file in the _data folder for any Jekyll site hosted on Github Pages.
The objective here is to provide little applications that use the native functionality of Jekyll and Liquid for displaying static, data-driven applications, and when I need to write data back to the YAML files I use JavaScript and the Github API. The critical piece is the authentication with the Github API in a 100% client-side environment (ie. Github Pages). This is something I've used OAuth.io before in the past, and my own Github OAuth proxy, but for these projects I want them to be forkable, and all you need is a Github personal token to access (which all Github accounts have) to access.
YAML In The _data Folder In Jekyll Sites
When you put YAML into the _data folder for any Jekyll driven site hosted on Github some interesting things become possible. Jekyll takes the YAML and loads it up as an object you can easily reference using Liquid Markup. It all makes Jekyll perfect for building little data-driven micro tools, with the YAML as a core. If you need JSON, XML, Atom, or other representations, you can easily publish pages that output in these formats.
This YAML is accessible in the _data folder for the Github repository that houses this site. I just want to provide a simple Github Gists for reference in this story. This YAML will be the driver of static, as well as dynamic content and data used across this prototype micro tool.
Static Listing of YAML data Using Liquid
Next up is to display the YAML data available in the _data folder and render it for viewing. Using Liquid I am able to dynamically generate and HTML listing of all the data in the YAML, acting as the static listing of the products that I have in my data store. Here is the Liquid that dumps all the products in the YAML file:
Liquid does have a learning curve, but once you get the hang of it, and have some base templates developed--it gets easier. I've been able to recreate anything that I would accomplish dynamically with PHP and a MySQL database, but using Liquid and YAML data stores.
Editing YAML Files Client Side With Github API
I have more YAML data store, and a basic static listing of the data store, now I want to edit it. Using Github.js and the Github API I am able to mount the YAML files in the _data/ folder and list out on the page with text boxes for editing. This obviously won't work for very large YAML files, but for sensibly structured data, kept in my small bits it will work just fine.
Once I'm done working with the data, I can save the form, and I wrote some JavaScript that traverses the form, updating the YAML file using the Github API. The trick is that this form, reading from the YAML file, and writing to it via the API isn't allowed unless you pass in a valid personal token from a Github user who has access to the underlying repository.
My 100% Client Side YAML Editing Micro Tool
That is it. This is my base template for any micro tools I build that will allow for reading and writing YAML files that are stored in the _data folder. It may not seem like much at first glance, but it opens up for me a wealth of new possibilities when it comes to data-driven tooling and collaborative projects that run on Jekyll (not just Github Pages, as Jekyll can be hosted anywhere).
First, I'm offloading application operations to Github. Sure Github has some issues from time to time, but I've been running 100% on them for over two years, and it is more than sufficient for most needs. Github scales and secures my applications, and I don't have to be concerned with keeping the infrastructure up and running--I just have to keep track of my personal tokens.
Second, these apps are self-contained and forkable. Anyone can fork it, grab their own personal token, and get to work managing the YAML core of their application. This is important to me. I like my tooling like I like my APIs, little, forkable and disposable, and truly open source tooling that anyone can put to use.
This is just base template prototype. I'll come up with more sophisticated versions soon. I just wanted to get the base template for running apps 100% on Github together, then this simple example of reading and writing YAML data from a _data folder before I moved on. I have a couple of API micro tools I want to develop in the area of API design, and I needed this functionality to make it all come together.
The base micro tool template and this base micro tool YAML template are both on Github.
