Published on

Introducing GitHub Gist HTML Renderer

Authors
  • avatar
    Name
    Teddy Xinyuan Chen
    Twitter

gist.teddysc.me is a simple service that does a simple nice thing.

Table of Contents

Demo

Single File Mode (Default)

Just replace gist.github.com with g.teddysc.me or gist.teddysc.me in the URL.

https://gist.github.com/tddschn/22990876690398bd42cfaa4be87a546e (HTML Gist, unrendered)

⬇️

https://gist.teddysc.me/tddschn/22990876690398bd42cfaa4be87a546e (Rendered)

Multi-files Mode

If you want the visitor to have easy access to more than 1 file in the Gist, you can use the multi-files mode.

Just add ?m to the URL.

Example: https://g.teddysc.me/cd7f65f529aa85658270dfd897b7dbed?m (When username not supplied, defaults to my GitHub handle tddschn)

If the gist has more than 1 file and you do not include the m query parameter, only the 1st file will be rendered as HTML.

Why

I love sharing non-binary files on GitHub Gist - it's private by default, no one should be able to visit the page without the knowledge of the URL with a long hash, like this:

https://gist.github.com/tddschn/22990876690398bd42cfaa4be87a546e

But what has bothered me for a long, long time is that GitHub renders .ipynb files but not .html files, which sometimes is not what users want.

Because of this, I've been sharing HTML files on rpubs.com via a CLI tool I made to upload files to the site in a single command.

However, there's no access control on rpubs, everything is public and the URL is easily guessable, which sucks.

The only upside of using rpubs is that it shows people I'm somewhat an R user, which sounds fancy. 🤗

The Solution

There was a site, bl.ocks.org, which was a site to display rendered HTML files and d3.js snippets from Gist, which sounds really cool, but unfortunaly, it's no longer in service.

I believe the service was operated by one of ObservableHQ's founders, who also wrote d3.js and the site is the precursor for ObservableHQ.

I never got a chance to use bl.ocks.org, but people really loved it and I like it too because it sounds like something a hacker would make, just a simple service that does simple nice things.

On StackExchange people suggested using something like rawgit (3rd party service to render HTML from GitHub for you, sounds kinda sketchy) or just host your own static website and include the HTML file (overkill, too much hassle, no access control), so I decide to hack my own bl.ocks.org, with no d3 support.

So here it is, introducing g{,ist}.teddysc.me (both domains work):

https://gist.github.com/tddschn/22990876690398bd42cfaa4be87a546e

becomes

The snippet below shows how the URL is mapped to a GitHub Gist raw URL:

const testCases = [
  {
    input: 'https://my.domain/tddschn/22990876690398bd42cfaa4be87a546e/myfile.html',
    expected:
      'https://gist.githubusercontent.com/tddschn/22990876690398bd42cfaa4be87a546e/raw/myfile.html',
  },
  {
    input: 'https://my.domain/tddschn/22990876690398bd42cfaa4be87a546e',
    expected: 'https://gist.githubusercontent.com/tddschn/22990876690398bd42cfaa4be87a546e/raw/',
  },
  {
    input: 'https://my.domain/22990876690398bd42cfaa4be87a546e',
    expected: 'https://gist.githubusercontent.com/tddschn/22990876690398bd42cfaa4be87a546e/raw/',
  },
  {
    input: 'https://my.domain/anotheruser/1234567890abcdef',
    expected: 'https://gist.githubusercontent.com/anotheruser/1234567890abcdef/raw/',
  },
  {
    input: 'https://my.domain/johndoe/abcdef123456789/myfile.js',
    expected: 'https://gist.githubusercontent.com/johndoe/abcdef123456789/raw/myfile.js',
  },
]

Usage

Manual

Manually replacing gist.github.com to g.teddysc.me or gist.teddysc.me in the Gist URL.

Script

The bash script gist-create-output-processor.sh below captures stdin, runs sed 's/gist.github.com/g.teddysc.me/' only on the last line of stdin, and output stdin and the processed last line together.

#!/usr/bin/env bash

# Read and store all lines from stdin into an array
mapfile -t lines

# Count the number of lines
num_lines=${#lines[@]}

# Process the last line with sed, if there is at least one line
if [ "$num_lines" -gt 0 ]; then
    last_line_processed=$(echo "${lines[-1]}" | sed 's/gist.github.com/g.teddysc.me/')
fi

# Output all lines
for line in "${lines[@]}"; do
    echo "$line"
done

# Output the processed last line, if it exists
if [ "$num_lines" -gt 0 ]; then
    echo "$last_line_processed"
fi

gh gist create my-fancy-html.html | ./gist-create-output-processor.sh
- Creating gist my-fancy-html.html
✓ Created secret gist my-fancy-html.html
https://gist.github.com/tddschn/ddc8c3ea22d61fc67e979c1d95f4ac45
https://g.teddysc.me/tddschn/ddc8c3ea22d61fc67e979c1d95f4ac45 # <- new line added here

What I use in my .zshrc

# prefixing command with `command` just to prevent alias expansion (I defined too many aliases to I do this to be safe)

tee_to_tty_and_copy_without_newline() {
        command tee /dev/tty |\
        command tr -d '\n' | pbcopy
    }

alias -g GTM='| gist_teddysc_me_url_processing | tee_to_tty_and_copy_without_newline'
function gist_teddysc_me_url_processing() {
    command sed 's/gist.github.com/g.teddysc.me/' |\
    command sed 's:/tddschn::'
}

alias gisttm='gist_create_gist_teddysc_me'
gist_create_gist_teddysc_me() {

    if [ -z "$1" ]
    then
        command 'gh' 'gist' 'create' | gist_teddysc_me_url_processing | tee_to_tty_and_copy_without_newline
    elif [ -z "$2" ]
    then
        command 'gh' 'gist' 'create' "$1" | gist_teddysc_me_url_processing | tee_to_tty_and_copy_without_newline
    else
        echo 'Using multi-file mode'
        command 'gh' 'gist' 'create' "$@" | gist_teddysc_me_url_processing | awk '{print $0 "?m"}' | tee_to_tty_and_copy_without_newline
    fi
}

So if multiple files are passed, ?m will be appended to the URL.

gisttm *.html
Using multi-file mode
- Creating gist with multiple files
✓ Created secret gist aisb-0515-message-count-by-party.html
https://g.teddysc.me/a0507ad12558c69348f5c4c88d0fb483?m

Chrome Extension

Use this extension to do the manual work for you when you already opened the link in the browser:

https://github.com/tddschn/url-regex-replace-chrome-extension

Chrome Web Store

Limitations

  • The ?m page won't be able to find any of the files if you have multiiple revisions of the Gist. Just re-upload all files and use the new URL.
Discuss on Twitter • View on GitHub