Skip to content

Better Footnotes in Ghost with Obsidian

Because text is limited to the domain of one direction ^ftmvri, adding breaks in the tedium for the reader is critical for engagement. Footnotes do a great job of this.[1] In addition, footnotes play the important role of allowing the writer to convey information that is akin to world building (basically the way "meanwhile" is used on TV shows) without having to use other symbols like "--" or ";" to symbolize a change in pace.

This doesn't mean footnotes are easy -- for the writer or the reader.

In books, the reader has to make the conscious decision to stop reading to go to the bottom of the document. This runs the risk of disrupting flow or even worse, causing the reader to stop all together. Alternatively, the reader can read all the footnotes at once after finishing a piece, but this sucks too. Most often, readers will be tired after consuming a whole article/blog/chapter, and footnotes just feel like more work.

For the writer, there is a choice to be made about whether to put something in a footnote or find a way to fit that information into the overall word budget of the piece. Not at all pleasant!

So are we just shit out of luck?

Fear not friends, if you too have a footer fetish, there is a light at the end of the tunnel!

Thanks to the web, we can use CSS and JS to hide information that sits right in the middle[2] of the flow of the piece. Not only that, but we can put images in footnotes,[3] or even full quotes and links![4] And best yet, all the footnotes are hidden behind cute ellipsis, and don't take up real estate at the bottom of the post!

Enough preamble, let's add some footnotes!

In Obsidian

Firstly, in Obsidian you're going to want to install the Footnote Shortcut plugin. This will allow you to create footnotes with a single hotkey (I mapped mine to alt-shift-f).

Next, if you publish to Ghost[5] you're going to want to use the Obsidian Ghost Plugin. This plugin converts markdown to HTML with markdown-it.[6] Specifically, and this is important so pay attention(!) you are going to want to use my fork here: bramses/obsidian-ghost-publish. This fork has the code you will need to run the footnote logic[7] as well as including other nice updates (The Obsidian Ghost Plugin).

That's all you really need on the Obsidian side of things.[8] Let's take a look at what we need to do in Ghost.

In Ghost

The core of the footnote experience is littlefoot.js. It handles pretty much everything, so all we need to do is make it play nicely with Ghost.[9]

Most importantly, you need to be able to edit the theme in Ghost, specifically gulp.js and default.hbs, so if you don't have a custom theme going, this tutorial will be harder to complete. This tutorial will walk you through a deep dive of how to do this, but in short:

  1. Inside your theme, run npm install --save littlefoot
  2. add littlefoot to gulpfile.js, mine looks like the code below:
function js(done) {
    pump([
        src([
            'node_modules/@tryghost/shared-theme-assets/assets/js/v1/lib/**/*.js',
            'node_modules/@tryghost/shared-theme-assets/assets/js/v1/main.js',
            'assets/js/lib/*.js',
            'assets/js/main.js',
            'node_modules/littlefoot/dist/littlefoot.js' // https://aspirethemes.com/blog/ghost-theme-load-scripts
        ], {sourcemaps: true}),
        concat('main.min.js'),
        uglify(),
        dest('assets/built/', {sourcemaps: '.'}),
        livereload()
    ], handleError(done));
}

  1. in screen.css add the following line to the imports:
@import "../../node_modules/littlefoot/dist/littlefoot.css";
  1. In default.hbs add the following script to the footer, right above </body>:
<script>
  littlefoot.littlefoot({
    activateOnHover: true,
  }) // Pass any littlefoot settings here.
</script>
  1. Run yarn zip to zip your theme
  2. Upload the zip to your theme in Ghost

That's it! Congrats on your new, sexy footnotes![10]


If you like what you read, please hit that Subscribe button in the corner to join other thinkers in this community! I send out multiple think pieces or Maps of Content a week as well as many notes that can only be seen by subscribing to the RSS feed above.


  1. or do they?…ok yeah they do

  2. Everything, everything'll be just fine
    Everything, everything'll be alright

  3. https://bram-adams.ghost.io/content/images/2023/02/leda.jpeg
    leda.jpeg
  4. Jimmy Eat World - The Middle (Official Music Video) - YouTube

  5. which I safely assume you do since you're reading this tutorial

  6. and the markdown-it-footnote plugin, of course!

  7. Ghost needs to upload footnotes as an HTML card or the API swallows the markup for some annoying reason

  8. One more thing. You probably want to install Linter and enable footnote re-indexing to make sure footnotes stay in order

  9. easier said than done…

  10. I hope we got off on the right foot!

Comments