Polymer + Markdown + GitHub simple “CMS”

Easy things were hard, now that the hard things are easy (almost) nobody wants it anymore. :(

Long time has passed since the days when it was difficult for me to build websites that my clients could edit without the need to call me.

It was the time around 2005/2006 and to tell you the truth, it wasn’t so easy for a lot of webdesigners, but fortunately the WordPress/CMS revolution was just around the corner…

A decade later so many things happened on the frontend side of the Web and we are so overwhelmed by the number of choices available when we need to make websites with content editable by other people (or in the end… just by us!) that it becamed difficult to have a simple solution for (very) simple projects/websites.

A simple user case

Let’s imagine you have to build a small websites or landing page, you want something fast to load and this is the main reason you may want to avoid a classic CMS (because we all know that static HTML pages are way faster than serve-side computed pages) and since you want just a single block of content to be editable, a database would be a waste of resources. Plus, it would be nice to host the website and manage its content for free.

So, what do we need?

Fortunately, just a couple of things

  • A GitHub repo
  • Polymer, a WebComponents library from Google
  • Marked-Element & Juicy-Html, two components built on top of Polymer

I suggest you to install the required library & components via Bower so you can simply use this command:

bower install polymer PolymerElements/marked-element juicy-html

Jump on a code editor

First things fists, add this code on the <head> of your website

Since Polymer it’s a library based on the new HTML specification of the Web Components we need to load a polyfill to make it works on all major browser. Today it’s fully supported only by Chrome, but things are getting better each day, so we won’t need the polyfill anymore sooner than what we think.

The last two lines imports the two components we have downloaded a few moments ago.

Now let’s create a new empty Html file that we will use for the content, since I’m feeling very creative, I will call it content.html . Inside this file we will use the <marked-element> that will parse and render a markdown content:

This is the basic use of the <marked-element> as it is described by its documentation. The text inside the script tag will be the markdown content we want to edit later.

Now we need to import this file inside our website, to do this we just need to add this tag on the desired html page:

Our code is finally complete!

Publish & edit

We will use a GitHub page to host our website, so inside our repo let’s create a new branch and call it gh-pages and push everything!

Check your GitHub page url to see these simple static-dynamic website published.

Now if we want to edit the content area of our website we just need to click on the “content.html” file from the GitHub repo UI , make some changes and make a commit.

Editing the content.html file directly from the GitHub repo UI

Check again your website (watch out for the browser cache!).

Cool! But I’m lazy and want some complete code

You can see a live demo of this tutorial on (guess what!) a GitHub page, and obviously all the related code is available on the demo repo.

The template layout is provided by StartBootstrap.

But wait… there is Jekyll out there!

I’m not even saying that Jekyll isn’t good or simple enough, my point with this article was to show another editable-static-webpage workflow that once setup give you the advantage of a fast loading website

The downside

The main downside of this approach is that loading external content and rendering new Html elements on the client side is extremely bad for SEO.


Bottom note: this is my very first time writing a (technical) article in english, so please be kind in reporting typos and errors :-)

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.