Joplin Export Procedure for Jekyll Sites

Lounge
1

Hey, all!

I’ve been using Joplin for mobile drafting for my blog (still getting set up). One frustration I was having was exporting posts, especially with images, in a way that it could be easily put into my Git repository for use in my Jekyll site.

Thought I’d share the solution I came up with.

TL;DR
  1. Change your Joplin notebook name to “_posts”
  2. Add a “_resources” folder to the root folder of your blog repo
  3. Modify the “config.yml” file, to add “_resources” to the “include” section, so Jekyll knows to check this folder when building the site.
  4. Export your note to markdown with front matter, to the root folder of your blog repo
  5. In your repo, add the YYYY-MM-DD prefix and slugify the title of the post.
  6. Commit and push your changes to origin.

Background

I’m using the Minimal Mistakes theme. The relevant file structure in the repository is:

- /
  - _posts
    - YYYY-MM-DD-slugified-title.md
  - assets
    - images
      - embedded_photo.jpg
      - other_photo.jpg

When I export a note with an image from Joplin to Markdown (with or without front matter) it exports as follows:

- SelectedFolder
  - NotebookName
    - Note Title.md
  - _resources
    - embedded_image_id_number.jpg

Obviously, these don’t match.

Considered Fixes

Change Joplin Export Format

This was my first instinct.

The Markdown Export let me pick what folder to export to, so I looked for a setting that would allow me to change the folder that images would export to. I couldn’t find one.

I tried to find a way to change Joplin’s internal file structure, so that the relative path from the note to the image would match that structure in my blog’s repository. Couldn’t find anything like that, and saw on the forums that it wouldn’t be possible.

I searched for a plugin that would export the way I wanted it to. It didn’t seem to exist.

So modifying Joplin’s behavior seemed to be out.

Change the Repo and How Jekyll Interacted With It

For a minute, I considered adjusting the folders in the repo, so that Jekyll would be looking for my posts in a folder that matches my Joplin notebook name, and for the images in a _resources folder.

That freaked me out. I am not experienced enough with Jekyll to be willing to make big file structure changes.

The Actual Solution

I kind of combined both options.

In Joplin, I created a new notebook, named “_posts”.

In my repo, I made a folder named “_resources”.

In the repo, I edited the “config.yml” file, so the “include:” section had “_resources” listed. This makes Jekyll use the resources folder to build the website.

What this does:

So now, the relevant repo structure is (changes bolded):

- /
  - _posts
    - YYYY-MM-DD-slugified-title.md
  - **_resources**
    - embedded_photo.jpg
    - other_photo.jpg

Now, I can export to markdown from Joplin, and select the root directory of my repo as the target. When it exports, the repo will then look like this (new files bolded)

- /
  - _posts
    - YYYY-MM-DD-slugified-title.md
    - Note Title.md
  - _resources
    - embedded_photo.jpg
    - other_photo.jpg
    - **embedded_image_id_number.jpg**

This is great. The blog post is in the right folder. The image is in a folder that Jekyll knows to look in.

Continued Issues

There are still a couple issues.

File Names

The file name that Joplin outputs is not in a format that Jekyll will recognize. I have to go in and slugify the file name, and prefix it with the YYYY-MM-DD date code that Jekyll needs.

That’s manual work, but it’s manageable, and it’s difficult to make a mistake on, so I’m ok with doing that myself.

Markup Issues

There is one markup incompatibility I’ve found. The formatting for footnotes, which I’ve been using extensively, is not consistent between Joplin and Markdown (specifically Kramdown).

Joplin has a unique inline footnote that Kramdown does not recognize.

I have realized that Joplin does recognize the more standard footnotes, but they’re less convenient, and I do have some existing Joplin notes that have the inline footnotes.

Action Items

I have a few things I’m working on for better Joplin-to-Jekyll export.

  • A python script that converts the file names to be Jekyll-compatible
  • A python script that checks for markdown that is convenient in Joplin, but incompatible with Kramdown, and attempts to fix it.
  • A python script that moves or renames an image file, checks for markdown files that reference that image, and updates those references.
  • Turning those into Joplin plugins that can be used during export
  • Making a Joplin plugin that allows you to define the file path for exporting embedded images

All of these are a ways away from being started, let alone usable, let alone publishable. I’m an engineer, but I’m not a software developer, so this is. . . Outside of my wheelhouse.

Conclusion

That’s about it. It’s not a complicated procedure, but as someone who prefers machine shops and design over software and networking, it took me a few hours to figure out that this was possible.

I figured I’d try to save someone else that same difficulty.

1 Like