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>