Refactor: Unify HTML and Markdown notes into a single Markdown-based note type

[gravelfreeman]

I want to address something that has come up on Discord and has been on my mind for quite a while. I had already started drafting this in the past, so I decided to clean it, since I think it's the right time to share this.

I would really like to see Poznote eventually commit to one canonical note format: Markdown.

The important distinction is that this does not mean removing the visual editor.

Instead, Markdown would become the single source of truth, while users could choose how they want to interact with that content:

• Visual editor
• Markdown editor
• Markdown + Preview / Dual Pane

From a user's perspective, there would simply be one note type with multiple ways to edit it.

Problems

HTML notes and Markdown notes are already approaching feature parity, yet they still behave as two separate systems.

This creates complexity in many places.

Development and maintenance

Every feature potentially has to be:

• implemented twice;
• tested twice;
• debugged twice;
• kept consistent between two editors;
• documented for two different workflows.

A bug also has to be identified as either:

• HTML-specific;
• Markdown-specific;
• shared between both;
• or caused by conversion between them.

That makes bug reports more complicated for users and debugging more complicated for you.

Visual editor

The main advantage of HTML mode is the live visual editing experience.

But the editor being visual doesn't necessarily mean the underlying note needs to be stored as HTML.

The visual editor could simply be another representation of the same Markdown document.

This would preserve what is great about HTML mode without requiring HTML to remain a separate note type.

Conversion

Right now, switching editing styles means converting the entire note.

That introduces questions users shouldn't really have to think about:

• Will something break during conversion?
• Will diagrams survive?
• Will formatting change?
• Can I safely convert it back?
• What happens to content Markdown doesn't represent perfectly?

For example, if a note contains an Excalidraw diagram, I may hesitate to convert it simply because I don't know exactly what will happen.

Ideally, switching editors should feel as harmless as switching views.

The document shouldn't change, only the way I'm editing it should change.

Workflow

Sometimes I start writing in Markdown because it's fast and convenient.

Later, the note becomes more complex and I would rather continue working visually.

With a unified note format, I could simply switch editors.

• No conversion.
• No duplicated document.
• No concern about losing formatting.

Then, if something looks wrong visually, I could immediately switch back to Markdown and inspect the source.

Interoperability

Using Markdown as the canonical format has another major advantage: the user's data remains portable and understandable outside Poznote.

At any moment I could:

• copy a note into GitHub;
• edit it in another Markdown editor;
• inspect the raw document;
• use it with Git;
• process it with ai, scripts or external tools;
• export or migrate my notes more easily.

At the same time, someone who doesn't care about Markdown would never have to see Markdown syntax at all.

They could spend their entire time using the visual editor.

That gives both types of users what they want without maintaining two fundamentally different note systems.

How

Instead of:

• HTML Note
• Markdown Note

There would simply be:

• Note

And the editor could switch between three views.

The existing button in the right-side menu could cycle between the three states:

• [paper icon] WYSIWYG mode
• [MD] Markdown Mode
• [dual pane icon] Dual Pane Mode

Additional advantages

I think this architecture would also have several long-term benefits.

One source of truth

There is only one canonical representation of the document.

That should reduce synchronization and conversion problems.

Smaller testing surface

Instead of testing combinations such as:

HTML
Markdown
HTML → Markdown
Markdown → HTML

the focus becomes:

Markdown document → different editor views

That's a much smaller state space.

Simpler onboarding

New users wouldn't have to understand the difference between an "HTML note" and a "Markdown note" before creating their first note.

They simply create a note and aren't tied to a specific editor.

Simpler documentation

Documentation could explain one note format and three editor modes instead of two separate note systems.

Easier troubleshooting

If something looks wrong in the visual editor, the user can immediately inspect the Markdown representation.

This makes bug reports more useful as well.

More predictable feature development

Features such as diagrams, images, tables, callouts, code blocks, embeds, etc. would have one canonical representation instead of potentially needing different implementations depending on the note type.

Better workspace customization

Eventually, workspaces could even choose a default editor mode.

• Documentation workspace → Markdown
• Student workspace → Visual
• Developer workspace → Dual Pane

<3

Since I've been using Poznote, the dual note types have added quite a bit of friction.

This morning in particular, while reporting editor issues, I realized how much additional complexity there is because of that.

I don't feel the benefits of having two separate note formats currently outweigh that complexity.

A single Markdown document model with multiple editor views would, in my opinion, make Poznote:

• simpler for users;
• easier to test;
• easier to maintain;
• easier to debug;
• more portable;
• and easier to extend in the long term.

Most importantly, it wouldn't require choosing between Markdown users and visual-editor users.

Both could use exactly the same notes, just through the interface they prefer.

For me, this would be one of the most meaningful architectural improvements Poznote could make.

What do you think?

[timothepoznanski]

Thanks for taking the time to write this up!!! 🙏

Let me say it clearly first: I completely agree with what this could bring. One note type, several ways to edit it, no conversion, portable data, less code to maintain and test, simpler documentation and bug reports. Having two note types creates real work for me, and I would love to have what you describe.

But Poznote also has a history, and it explains why things are the way they are.

Poznote originally only had rich text notes. What I wanted was to be able to paste a web page directly into a note and have it rendered immediately. I also wanted to be able to open my notes without Poznote and still see the images, colours, formatting, etc. At the time, HTML was simply the perfect format for that.

A few years later, I wanted to be able to paste AI output just as easily, and that's one of the reasons Markdown notes were added.

So the two types ended up solving two different needs. I've actually tried twice to unify them, and both times I eventually came back to the current design.

The main problem is that I don't think the current visual editor can simply become another view of a Markdown document. Today, it's a free-form rich text editor where the HTML itself is the source. To make it edit Markdown, every save would have to go from HTML → Markdown → HTML without losing anything.

But Markdown simply cannot represent a lot of what HTML notes currently support: text colours, font sizes, merged table cells, pasted web pages, formatting pasted from Word or OneNote, etc. Either those features would have to disappear, or we'd have to store inline HTML inside the Markdown. And in that case, a large part of the portability benefit is lost anyway.

The projects that offer both views on the same Markdown document generally solve this by using a much more constrained visual editor that can only produce what Markdown can represent. That's quite different from the current Poznote editor, which is intentionally more free-form and rich.

So for Poznote, this wouldn't really be a refactor. It would mean replacing the visual editor and migrating all existing HTML notes, with some loss of formatting for users who rely on features that Markdown cannot represent.

Regarding conversion: there is an option to duplicate the note before converting it, so you can check the result without losing the original. That's the safest way to convert a note you care about, for example one containing an Excalidraw diagram. The conversion isn't perfect, but I'm continuously improving it, and specific cases where it gets something wrong are actually very useful to me as bug reports.

[gravelfreeman]

What I wanted was to be able to paste a web page directly into a note and have it rendered immediately.

That made perfect sense when Poznote was created. I just think the trade-off has changed 😃

Today, I would rather see pasted HTML treated as an import format, not as a native editable note format. Paste a web page, convert it to clean Markdown, keep the images where possible, and improve that importer over time. If exact preservation matters, we now have tools like Karakeep/Linkwarden, or the page can simply be attached as a PDF.

That gives users most of the original benefit without forcing you to maintain an entire HTML editing stack forever.

pasted web pages, formatting pasted from Word or OneNote, etc.

This is actually part of why I would move away from HTML.

Every application and website can generate different markup, styles and edge cases. At some point it becomes difficult to even distinguish a Poznote bug from weird HTML produced by another application.

A constrained Markdown editor has fewer possibilities, but those constraints also make it far more predictable and maintainable.

text colours, font sizes, merged table cells

I think this is where accepting some limitations is worthwhile.

Colours, font sizes and normal tables already cover essentially everything I personally expect from a note-taking application. I don't think Poznote needs to reproduce everything HTML can technically represent.

The boundaries of Markdown are what make it great.

or we'd have to store inline HTML inside the Markdown.

I wouldn't do that either.

Once arbitrary HTML starts living inside Markdown, a lot of the simplicity, portability and predictability you're trying to gain disappears again.

I'd rather have a clearly defined Markdown feature set and make that exceptionally solid.

with some loss of formatting for users who rely on features that Markdown cannot represent

I wouldn't force existing users to migrate immediately.

HTML notes could remain readable indefinitely because browsers already render HTML extremely well. They could simply show a small banner explaining that the note is using a read-only rich text format.

I would actually keep that read-only HTML format forever. That way, someone who doesn't use something like Karakeep could still quickly paste and preserve a web page directly inside Poznote without creating an attachment or converting it immediately.

The important distinction would be that HTML remains a format Poznote can display, but not a format Poznote has to edit. Maintaining a read-only HTML renderer should be dramatically simpler than maintaining a full rich text editor and all of its editing edge cases.

The banner could then offer an Edit / Convert to Markdown button. The moment the user wants to modify that note, Poznote converts it to Markdown and migrates the note to the actively supported format.

That also means existing users wouldn't have to convert anything unless they actually want to edit it. If preserving the original formatting matters more, they can simply leave the note as read-only HTML forever.

The biggest thing that changed my mind is actually using the HTML editor more seriously. It made me realize you're effectively maintaining two note-taking applications inside one.

The bug surface of a free-form HTML editor is practically endless, and every hour spent dealing with pasted HTML, browser quirks, Word markup or formatting edge cases is an hour that could go toward making one editor much better.

And I think this becomes an even bigger issue if Poznote ever wants proper clients on desktop, iOS, Android, tablets, etc.

Maintaining one rich HTML editor consistently across all of those platforms is almost unrealistic for a small project. Each platform has different text editing behavior, rendering engines, keyboard handling, selection quirks, clipboard behavior, touch interactions and WebView limitations. The number of combinations and platform-specific bugs grows very quickly.

A constrained Markdown model gives every client a much smaller and more deterministic target. You can have different editors on different platforms while still working against the same simple document format underneath.

That makes native or semi-native clients much more realistic to maintain long term.

So I don't really see dropping active HTML editing as removing functionality. I see it as choosing a smaller and more predictable scope.

If it were my decision, I would make Markdown the only actively developed and editable note format, keep HTML as a permanent read-only format for legacy notes and quick web captures, and invest heavily in a good HTML → Markdown conversion path whenever the user wants to edit one.

I think the maintenance burden of supporting two editors will only increase with time, so the earlier that line is drawn, the more effort can go toward features that benefit everyone.

[timothepoznanski]

Thanks for sharing this. I think it is very right and relevant, especially the point that “the maintenance burden of supporting two editors will only increase with time.” I think that is what worries me the most, which is why I’m trying to simplify things as much as possible. I probably should have said no to some choices along the way (like supporting OneNote pasting, for example).

However, it doesn’t change the fact that I don’t think the current visual editor can simply become another view of a Markdown document.

Today, it is a free-form rich text editor where the HTML itself is the source. To make it edit Markdown, every save would have to go through HTML → Markdown → HTML, without losing anything in the process. That is a much bigger architectural change than simply adding another editor/view.

And there is also another important point: what about people who don’t even know what Markdown is, or simply don’t care about learning it? Some people use Poznote precisely because it works like a traditional rich text editor. They just want to write and format their notes without having to think about Markdown at all.

So I completely agree with the goal of simplifying the architecture and reducing maintenance. You really don’t need to convince me of all the benefits of moving to Markdown-only. I know them, and I’ve actually tried it. I just realized that it is not as simple as I initially thought.

[gravelfreeman]

And there is also another important point: what about people who don’t even know what Markdown is, or simply don’t care about learning it?

I reinstalled Docs from La Suite because it’s much easier to show this in a video than to try to explain it.

Capture.video.du.2026-10-06.12-35-26_compressed.mp4

In my opinion, this approach is better than Obsidian for people who aren’t familiar with Markdown. What you see in the video is essentially a set of visual shortcuts that write the Markdown for you in the background.

Poznote already does most of this. When you switch to edit mode, you already have the toolbar, so users don’t need to know Markdown.

The main limitation is that you’re forced to edit in this view:

What I’d like is to also be able to edit the Markdown directly in this view:

This wouldn’t replace the rich text editor. It would simply be the default Markdown view when opening a document, and users could choose a different default in the settings.

So there would be three modes if we're excluding the default view/read mode:

• Dynamic
• Markdown
• Dual Pane

[timothepoznanski]

Ok, I get it now! I was focusing on modifying the HTML editor, which seemed very difficult to me because of all the dependencies. But actually, I should focus on the Markdown editor instead, and since I already have CodeMirror in place, it should be much easier to do.

[timothepoznanski]

Release 6.110.0

The Markdown editor gets a live rendering mode, where the note looks like its preview while you type, and tables can now compute totals.

Important

Live rendering is still a work in progress. A setting to never show the Markdown syntax, so that you type as in a rich-text editor, is not finished yet and will come in a later version.

[gravelfreeman]

Tim! This is incredible, I am so happy 😃 I just tested it and I'm impressed how good it is already. Let me know if you prefer that I let you work on it before reporting bugs or if you prefer reports asap. Thank you for implementing this, Poznote will soon have feature parity with Docs from La Suite and that's unbelievable!

[timothepoznanski]

I knew it would make you so happy. 😁 I'm still working on the settings to completly hide the markdown but I'm struggling a bit. But yes go forth for reporting bugs please. I tried to test as much as possible but I probably missed several issues. I'll fix them one after the other. I now have hope to be able to remove html notes but there is a lot to do yet.