Peter Stuifzand

Compatibility of Markdown in Logseq

These are some of my thoughts about Markdown in Logseq. In this note I try to find the assumptions behind the conflict.

This is thinking I did on my and is not associated with how Logseq will work now or in the future, this also does not represent goals of the Logseq team. This is what I think the goals could be.

The conflict

Goal tree

This is the goal tree, for some of the features we “need”.

Current reality tree

A current reality tree describing the situation with Markdown as the source of thruth for content of the graph.

A current reality tree describing the situation with Markdown as the source of thruth for content of the graph.


For a conflict cloud we need to find the assumptions behind the arrows. What makes us think that the arrows are real? What do we assume to be true? This tree was created by copying and pasting the arrow in the sidebar. The blocks in the cloud are called the goal (A) at the left, the needs (B and C), and the wants (D and D’). The goal and the needs can be found in the goal tree. The wants are in the current reality tree (CRT). The CRT describes the problem. The arrows are named for the two blocks that it points between.

It would be nice if it was easier in Logseq to add an outliner for the arrows in the whiteboard. This is a usecase for whiteboards that seems to be something I would use.

whiteboard arrow: AB

In order to make Logseq a great note taking application now and in the future, we need to add new features.

  • We need new features
  • There could be a maximum number of features that should be enough for everybody?
  • We need more features that Markdown can support?
  • Many of these features are not supported by other apps. When importing files from other apps, or vice versa, the syntax is not supported.
  • When publishing the syntax needs to be rewritten.

whiteboard arrow: AC

In order to make Logseq a great note taking application now and in the future, we need compatibility with other apps.

  • People use the Markdown files for other purposes: other apps, or publishing, or manual edits, sharing
  • A Markdown file can be shared easily with other people, another graph, or other apps
  • Markdown files are compatible with other apps
    • What features (with syntax) are already outside the support of Markdown? There are more features that Markdown does not support.
      • Links [[...]]
      • Tags #tag
      • Block references ((...))
      • Block embeds {{embed ((...))}}
      • Properties prop:: val
      • Queries {{query (...)}}
      • Macros {{macro ...}}
      • Highlight/mark formatting ==mark==
      • more?
    • Logseq already uses incompatible syntax in the Markdown files, is this a problem?
      • When publishing Markdown files created by Logseq you need to remove or add support for the syntax that was added. The unsupported syntax is included as-is in the generated HTML.
  • Which Markdown features are not used?
    • Paragraphs
    • Ordered lists (only inside blocks)

whiteboard arrow: CD

In order to add new features (easily), we want Logseq to use structured files (or a database)

  • New features can be added easily with EDN files.
  • EDN file are not compatible with other apps
  • Features in the EDN files probably can’t be easily converted to Markdown (otherwise the conflict would not exist)

whiteboard arrow: CD'

In order to maintain compatibility with other apps, we want Logseq to use Markdown files.

  • New features are difficult to add with Markdown files.
  • When new features added to Markdown files, the files become less compatible
  • Other apps don’t support the new syntax in the Markdown files for the new features.

whiteboard arrow: conflict (DD')

We can’t use both structured files or Markdown files at the same time. Using structured files, excludes the use of Markdown files and vice versa.

  • We can’t use Markdown files and EDN files at the same time.
  • When we use both files types at the same time we need to add incompatible syntax or the files can’t be used with other apps.
  • If the user can switch between which file type to use, they have less features, or incompatible syntax
  • Does all syntax have to be saved to Markdown files?
  • Do we need to use the Markdown files as the source of truth for the content of the graph?
  • Is it enough to generate the Markdown as needed for people who want to publish? Or for other uses.
  • Do we need to auto-import changes to Markdown files?
    • This is needed for people who uses two apps on the same graph. Changes in one app, become visible in the other app.
    • People can use a powerful external editor. Logseq does not support certain editor operations, like search and replace.

That certain features are not supported by Markdown and Markdown apps, means that we need to add extra software to convert these types of syntax to other Markdown (or HTML) syntax for this to work in a browser (or other app).

Check the truth of the assumptions

For every assumption you can ask yourself “Why?” and answer with “because…”. At some point you’ll find an assumptions that does not make sense.

In Logseq brackets conflict I wrote about the conflict that appears, because the reading and editing is separated. There Markdown creates a conflict between better reading and better writing.

© 2023 Peter Stuifzand