11tyCMS: Trapped in image and markdown hell.

posted on Jun 4, 2025

Wow. 11tyCMS has gone through some really rough times these past 24 hours. What happened you ask? Well:

• I found out that MDXEditor, the core WYSIWYG editor that I was using for 11tyCMS is broken. There's a fatal bug that probably wont get fixed where the longer you type for, the laggier the editor gets.

• As a result, I then had to go on a MASSIVE rabbit hole to find a decent editor with markdown and rich text support.

• I then got trapped in the rabbit hole of figuring out how the hell to get electron to read relative file paths for an 11ty site's images.

Lets talk about it... Strap in, this one's gonna be a long one.

MDXEditor: Lag lag lag

So... Turns out that MDXEditor, despite being so well put together, has some serious issues with performance. You'll notice that if you open up the sample editor they have on their website right now, and just type away for 5 minutes: that it gets slower and slower, until it gets so laggy it's unusable.

I was about to submit an issue... Until I searched closed issues, only to find someone else with the same issues as me 6 months ago reporting it. Unfortunately, the issue got closed without explanation by the maintainer and tagged as something that wouldnt get resolved. So, as far as I'm concerned, MDXEditor is as good as dead.

Finding an markdown editor replacement

So this sent me on the wild goose chase to replace MDXEditor. Good. GOD. Here are the options I explored:

EasyMDE

This is going to sound stupid, this should be almost perfect on paper. Its a rich text editor, it supports and is designed around Markdown. It supports images, and is infinitely customisable. Its also FOSS! But, after some testing here's what I found:

• The editor displays the markdown syntax, even after parsing it

  • I actually kind of like this, but it looks so cluttered. Sometimes you just want to edit text in a rich text editor with markdown shortcuts, rather than seeing all the guts.

In fairness, this sounds like a strong contender, even with the issues I point out... But honestly, I just want a nice rich text editor that works without having to see the markdown guts. My mind could be changed on this though.

uiwjs react-md-editor

Honestly, this was one of the options furthest from being viable for me. The editor UX isn't what I'm looking for in 11tyCMS, and it just doesn't feel right. It also cant parse the markdown as you're editing it, requiring you to split screen between your editor and preview to see how what youre writing looks like. Based on these reasons, I decided to rule this out.

react-markdown

This suffers from all the same problems as react-md-editor so I wrote it off.

TipTap

Now TipTap... God I hate how good it is. Why? Because its freemium. Its a big company who sells a subscription to TipTap to get access to more advanced features. Not a fan. But also? Its by far the most complete editor I've found that has decent markdown support. This sounds perfect right? There should be nothing stopping me from implementing this into 11tyCMS... About that.

I ended up ditching TipTap for one very annoying reason: Markdown support.

But Thinkymeat!, I hear you ask: "I thought you said it had decent markdown support?"

It does! When youre typing it. Want to set the contents of the editor with markdown? Nope. Not without paying money for their subscription.

This immediately killed my desire to use TipTap, especially when EasyMDE was so damn close.

To give you an idea of what horrific attrocities this unleashed:

• I did initially try to get around this limitation by creating a script to convert the markdown in a file to HTML to input into TipTaps editor, and then convert that HTML back into markdown on save.

  • This ended up being a horrific mess and a very untidy solution to a very silly problem.

🥳 Finally a solution: Milkdown

So... After 2 horrifying days of being stuck without an editor for 11tyCMS, I happened across Milkdown. THANK GOD!!! Basically, it takes all the magic of the markdown editor in Notion, recrates it and makes it FOSS. Fucking INCREDIBLE. It has full support for React and does rich text AND Markdown support beautifully. This library has features coming out the freakin' wazoo. There's nothing this markdown editor can't do and I ADORE it. I'll bet it can even run DOOM, probably even Crysis.

Anyway, jubilation aside: Implementing this was a nightmare. Mostly down to me being tired and brainfogged. I just couldnt get it to integrate that well with React, or it felt kinda wrong. Anyway, after bashing it with a hammer for hours and hours, I got the React library working. I found the docs a lil inconsistent because theres two versions of the editor: the full fat Milkdown editor, and the other more basic implementation of it. And a lot of the docs vary between the two.

BUT I'm happy to report: I'm writing this update to you IN 11tyCMS WITH Milkdown!!! It works beautifully and I love it so much. It has also bought an end to the long and hellish road that I got stuck on.

🖼️ Implementing image support

So this ended up in being a long and frustrating rabbit hole as well. Here was the problem before:

• My images for my blog in 11ty are all using relative paths like so: /media/image1.png (so the absolute path would be: /home/thinkymeat/TOMT/media/image1.png)

• Now Electron is a separate app that doesnt have full access to the file system by default. When 11tyCMS opens the 11ty site folder, it will parse the markdown files and try to display the images using the srcs defined for 11tys relative path.

  • This obviously wont work because Electron is running outside of that directory and doesnt have access to it anyway.

So now I'm faced with an issue... I had a few solutions:

• Extend the markdown editor (which was MDXEditor at the time) to reference the absolute file paths.

  • So: file://home/thinkymeat/TOMT/media/example.png

    • Except for... This didn't work. Apparently the web aint that simple, and for good reason too.

• Host a web server within the Electron app and statically serve up the entire 11ty site folder

  • But this is a huge security risk. If you store any envs in the folder, they will be served up.

  • I could have coded some security fixes for this to make it only accessible by Elecron, but it just seemed like a huge risk either way.

  • Anyway, this still wouldn't solve the aforementioned issue... The paths in the images would still be relative...

• Converting all the relative paths of images in markdown files to base64 pngs when opening, and then back to relative paths again on save

  • This would have been computationally intensive, and would have likely required stenography to save the file names of the files for the save part? That would have been a potential security risk too. No good!

So with no compelling solutions initially, I set out to try and solve the relative path issue and figure it out from there.

Fixing relative URLs

After a lot of troubleshooting, I figured it out:

• I found the REGEX to find all links in a markdown file, and therefore extract their URLs.

• From here, I check if its a proper URL or a relative file path.

  • If its relative, then we need to perform our magic, if its not, ignore it.

• Now, I can convert the relative paths to whatever I need to access them.

So I had a solution for this problem but for it to work, I still needed to figure out how I was getting the images to Electron in the first place. But I basically managed to manipulate the markdown file when you open it to convert the relative paths, then convert them back to relative again on save.

It was at this point where I figured that I could not use the file:// protocol to try and use absolute paths... Which lead me to my next solution!

Defining a new protocol

Yup. I found out that Electron has support for defining a protocol. So I simply defined a protocol called eleventy. Then I made it so that it basically points to the folder of the selected 11ty site. So now, if I want to access an image in my site I can simply just prefix the relative path with the eleventy protocol like so: /media/test.png . And it fucking WORKED. It worked beautifully. I was so so happy about it. A beautiful solution that worked well. Happy days!

Next up: upload support

Now we have images displaying within the editor, we need to add the ability to upload them. Thankfully Milkdown has some excellent support for this. I'll just need to code a custom handler for me to call a function on Electron's IPC thingy and it'll work perfectly.

Conclusion

Images and markdown editors are an unrelenting hell and I hate them. But I'm also endlessly happy that I've managed to implement it all OK.