2015-08-15

Turn Your Gist To HTML

TL;DR; I needed a blog & solved it in wee bit tedious but simple way

Lately, I've been doing a lot of side projects & talks. While I tweet most of my progress and research, when I finish a project, people ask if I documented the process somewhere.

I'm most comfortable writing long form docs in markdown format and I already have many notes on my gist as markdown file. So I made a script to pull .md file from gist and convert to HTML.

Using gist API is very simple

If you already have gist id (https://gist.github.com/[username]/[ID]), getting data via API is very simple. Just make GET request to https://api.github.com/gists/[id] and you'll get JSON back - check this out. No API key, No authentication necessary. (This applies to secret gist as well)
*When you are calling API from command line, you must set user-agent in the headder.

Markdown to HTML parser

I've tried few markdown to HTML parser and settled on markdown-it. "markdown-it" parse code block in github favored markdown to hilight.js compatible HTML. This was major win for my documentation purpose which will have many code samples.

This code block turn into...

    ```javascript
    var sample ='sample'
    ```

This HTML.

<pre>
  <code class="language-javascript">var sample ='sample'</code>
</pre>

Inject converted HTML to a template

Once you have a converted HTML, you can inject it to any file by doing handy dandy String.replace().

I made a template HTML with some place holder like {{content}} {{date}} {{description}} which will be populated with data returned from gist API.

Publish

After I convert gist markdown into HTML, I edit blog directory page, then manually deploy to my server. It is a little bit tedious, but then, I'm only going to publish once in few month, so this process is good enough.

The Script

Here is the script! To run it, I do following command and pass gist id as argument

node gist2HTML.js [gist id]

gist2HTML.js

var fs = require('fs');
var md = require('markdown-it')();

var gistID = process.argv[2]

fs.readFile('template.html','utf8', function (err, data) {
  if (err) throw err;
  var template = data;

  var options = {
    host: 'api.github.com',
    path: '/gists/'+gistID,
    headers: {'user-agent': 'nodescript'}
  };

  https.request(options, function(response) {
    var str = '';

    response.on('data', function (chunk) {
      str += chunk;
    });

    response.on('end', function () {
      var res = JSON.parse(str);
      var file = res.files[Object.keys(res.files)[0]];
      var html = md.render(file.content);
      var filename = file.filename.split('.')[0];
      var date = new Date(res.created_at)
      template = template
                  .replace(/{{date}}/g,date.toISOString().split('T')[0])
                  .replace('{{content}}',html)
                  .replace('{{title}}', filename.split('-').join(' '))
                  .replace('{{description}}', res.description)

      fs.writeFile(filename+'.html', template , function (err) {
        if (err) throw err;
        console.log('file created: ' +filename);
      });

    });
  }).end();
});

template.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>{{title}}</title>
    <meta name="description" content="{{description}}" />
  </head>
  <body>
  <article id="main">
    <time datetime="{{date}}" pubdate>{{date}}</time>
    {{content}}
  </article>
  </body>
</html>