GitHub Gists from Emacs Orgmode

Tue, 26 Apr 2022 12:37:00 +0530

TL;DR: I released my first Emacs MELPA package – ox-gist – An Orgmode backend to export and update sub-trees and buffers to GitHub gists. It was a great experience contributing to MELPA.

Motivation

I often share bits and pieces of my journal.org file with others, mostly for reading, some times for comments. The file contains different subtrees for each day with subtrees for different topics, meetings, articles, etc.

Orgmode lets you export subtrees to specific file names using the EXPORT_FILE_NAME property (and FILE_NAME buffer export option when exporting full buffers). It is easy to create these exported files on a publicly accessible webserver using the power of Emacs TRAMP mode. For instance, I often set the property to some thing like /ssh:muse-amuse.in:~/public_html/<filename> to publish stuff.

But, exporting to HTML is a distraction some times because I start fiddling with CSS and styling. Exporting to a simple org file doesn’t seem to cut it because there’s no styling at all, and making longer exports hard to read in a web-browser. Exporting to a GitHub Gist is a nice middle ground because GitHub renders Orgmode files reasonably well. Additionally, the comment functionality is pretty handy.

I could also directly use @defunkt’s excellent gist.el to share stuff as Gists. I’ve used it in the past, and it works well when I don’t care about having the contents of the Gist locally on my machine. It’s also quite easy to update existing/old Gists in this scenario, since there’s a single “source of truth” and gist.el makes it quite easy to update Gists.

But, this isn’t good enough when I want to have a “synced” copy of the text on my machine. Also, it doesn’t work very well when I want to share just a subtree from my notes file, and not the entire file. I’ve to export the subtree to a temporary Orgmode buffer and then create a Gist from that buffer.

Hackish wrapper around `gist.el`

A couple or so years ago, I wrote a wrapper around gist.el to let me post Orgmode subtrees as a Gist and also update them when I edited these subtrees locally. There was no support for exporting entire buffers since that wasn’t my use-case. This wrapper code was just a part of my .emacs and worked reasonably well for me.

A few weeks ago, I ended up procrastinating on writing and sharing notes for a discussion with a friend, and extracted this wrapper as a separate package – org2gist – to make it easy for other people to use.

MELPA submission and feedback

I submitted this as a package to MELPA while being skeptical about whether it would be accepted. I wasn’t sure if my thin wrapper around gist.el would meet MELPA’s criteria for a “Reasonably innovative package”:

MELPA provides a curated set of Emacs Lisp packages, not an exhaustive list of every single Emacs Lisp file ever created. By default, MELPA maintainers will reject packages that duplicate functionality provided by existing packages. Please try to improve existing packages instead of creating new ones when possible.

It was a pleasant surprise to get very helpful reviews from the MELPA maintainers. They not only thought the package was good enough to include in MELPA, but also looked at it’s code and gave great feedback — not just basic quality checks before accepting the package into MELPA.

I’m pretty sure mainting a package repository like MELPA is a lot of work, but as an end-user it mostly just worked for me and I never really gave it much thought. It was eye-opening to submit the package to MELPA and see first-hand the care and effort the maintainers put into what goes into the repository.

@riscy (a MELPA maintainer) suggested a different approach that I hadn’t thought of — turning the wrapper into an Orgmode Export backend.

Current version: `ox-gist`

It turned out to be a great idea which I ended up implementing. The user interface became much cleaner, since it used the Orgmode Export UI. And it also forced me to “complete” the feature-set by adding support for exporting entire Orgmode buffers to GitHub Gists, not just subtrees.

The package now adds an Orgmode export backend that lets you export a subtree or the whole buffer as a GitHub Gist, similar to how you’d export to HTML or LaTeX from Orgmode. The GitHub Gist ID is saved for each exported buffer or subtree and is to update a Gist when re-exporting an already exported subtree or buffer.

Outro

The package has now been added to MELPA as ox-gist. Feel free to give it a spin and give feedback directly to me or on the issue tracker!

I don’t know if anyone else would find the package useful and use it, though, MELPA tells me that 20-odd people atleast downloaded it. I’m happy this code may be to a handful of people.

Also, I now have a new found appreciation for MELPA and the work put into it by the maintainers. I’m glad I took the time out to submit this package to MELPA.

Thanks to Shantanu for reading drafts and helping me restructure this post.

Recurse Center, 2014-06-11

Wed, 11 Jun 2014 15:02:11 -0400

Plan

Continue with the Haskell tutorials, with additional reading from Real World Haskell.

Actual

Finished exercises 4 and 5.
- Learnt about Type classes in Haskell and how to create them and make data types instances of them.
- Also came across a new algorithm of sieving called the Sieve of Sundaram, which was discovered by a student. Surprisingly, I never heard of it before!

Miscellaneous

A few of us had an interesting discussion about various places people grew up in and visited, and the cultures, etc.
Idea: implement a GitHub dashboard for organizations (say, HS batches) that give you different statistics, and interesting graphs. (Use elm?) [Update: Tom is working on HS and GitHub integration. So, that’s perfect!]

GitHub Cue: Recommendations for GitHub Repos

Fri, 05 Aug 2011 00:00:00 +0530

If you aren’t already aware of it, I’m one of those people who goes around saying, “GitHub is my Facebook”. I spend quite a lot of time on GitHub, browsing the work of various people, looking at loads of interesting stuff that people built. I keep jumping between people pages and projects using the Watchers/Watching & Followers/Following pages. This way, I do come across interesting people and projects, but the SNR is too low. I wanted a better way to be able to see stuff, that I find interesting. That’s how the idea for this Chromium app – GitHub Cue – was born.

@baali and I hacked on this, during the last few days and got it working. It works as follows, (from the README) —

Scrapes all the descriptions of the repositories being watched by the user.
Key terms are extracted from this description text using the Yahoo Term Extractor.
A list of languages is obtained, based on the languages of the repositories, the user if watching.
GitHub searches are performed for a combination of 3 randomly chosen languages and 5 random key terms.
10 random repositories out of all these, are shown.

This is a very simplistic algorithm, but works decently for my purposes. Ideally, I would’ve liked to use a Collaborative Filtering algorithm, but I found the data to be too sparse, and the amount of computation to be too much to be done on the fly. I wasn’t really interested in pre-computing stuff and putting it onto my server. I settled down to the next best thing I could think of.

I would appreciate any further ideas and suggestions. Thanks!

Github on Noetic Nought