Logseq Note Taking App: The Markdown Outliner Explained

November 11, 2026 · 12 min read

Logseq Note Taking App: How Its Markdown Outliner Works

The Logseq note taking app is a free, open-source outliner whose classic file version saves your notes as Markdown files in a folder you pick. You write in bullets, link pages with double brackets and keep a daily journal. This guide shows what Logseq writes to disk, how to use it, and what the DB version changes.

What Is the Logseq Note Taking App, and Who Is It For?

So what is Logseq, exactly? It's a local-first knowledge base released under the AGPL-3.0 licence, with desktop apps and a web app. The classic version reads and writes plain Markdown or Org-mode files, and the Logseq repository describes the project as privacy-first.

Everything in Logseq is a block, which means one bullet. Blocks nest, so a page is an outline rather than a flowing document. The journal opens on today's date, which gives you somewhere to write before you've decided where a thought belongs.

That model suits some people far better than others:

  • Good fit: daily loggers, researchers who connect ideas across many topics, and anyone who already takes meeting notes in bullets.
  • Weaker fit: long-form writers. Essays and reports read awkwardly when every paragraph is its own bullet.
  • Weaker fit: people who need notes to look identical in every Markdown app, for reasons the sections below make clear.

If you're still choosing between tools, our roundup of Markdown note taking apps puts Logseq next to seven others. This page sticks to Logseq alone and looks at it from the file side.

Every Line Is a Block: How the Logseq Outliner Writes Markdown

The Logseq outliner follows one rule that shapes every file: each block starts with a dash and a space. A child block sits one level deeper. In the files we've looked at, including Logseq's own documentation graph, that indent is a tab character.

Here's a page called Project Atlas as it sits on disk:

tags:: project, work
status:: active

- ## Goals
	- Ship the scope document by Friday
	- Agree the budget with [[Finance]]
- Kickoff notes #meeting
  collapsed:: true
	- Budget is capped at 40k
	  id:: 6714b2c1-8f3e-4d2a-9c11-3b5e7a0d9f21
	- TODO Send the agenda to [[Design Team]]
- Decision log
	- Scope agreed, see ((6714b2c1-8f3e-4d2a-9c11-3b5e7a0d9f21))

Here's what each part does:

  • The first two lines have no dash. They're page properties, which Logseq keeps in the first block of a page.
  • - ## Goals is a block whose content is a heading. Headings live inside bullets, not above them.
  • Each tab-indented line that starts with a dash is a child of the block above it.
  • collapsed:: true records that you folded that block in the app. Property lines are indented to line up with the block's text.
  • The id:: line appears under a block once another block references it.

Underneath, these are ordinary nested lists. If list nesting or tab indents are new to you, read our guides to Markdown lists and indentation in Markdown. Logseq parses everything with its own parser, mldoc, so a few extras such as ^^highlight^^ only work inside Logseq.

Journals, Pages and Assets: Where Logseq Stores Your Notes

A file-based Logseq graph is simply a folder. When you create one, Logseq adds a small set of folders to it:

my-notes/
  journals/2026_11_11.md
  pages/Project Atlas.md
  pages/Projects___Atlas.md
  assets/diagram.png
  logseq/config.edn
  • journals/ holds one file per day. The default filename pattern is yyyy_MM_dd, so a note for 11 November 2026 becomes 2026_11_11.md.
  • pages/ holds one file per page, named after the page title.
  • assets/ stores images and other files you add to a page.
  • logseq/config.edn holds the graph's settings. You can edit it outside Logseq, and the docs say changes apply within a few seconds.

Page titles that contain a slash need special handling, since / can't appear in a filename. Graphs created in version 0.8.9 or later use a triple underscore instead, so the page Projects/Atlas is saved as Projects___Atlas.md.

You can also point Logseq at a folder of Markdown files you already have. Per Logseq's docs, it finds files in subfolders, so nothing has to move into pages/. It even detects notes made by Obsidian's Daily notes plugin, although new journal days still go into journals/. Our Logseq vs Obsidian comparison covers moving notes between the two apps.

Logseq Properties, Links and Block References in Plain Text

Logseq stores its structure as text patterns inside each Markdown file. Four patterns carry most of the weight.

Properties use key:: value. In the first block they describe the page, and anywhere else they describe that one block. The Properties docs list three rules worth knowing: names are case-insensitive and stored in lower case, an underscore becomes a hyphen, and a value can't contain a line break. A property with an empty value isn't visible or queryable.

Page links are [[Page name]]. A #tag or #[[two words]] links to a page in the same way. The built-in tags:: and alias:: properties also turn comma-separated values into page links.

Block references look like ((6714b2c1-8f3e-4d2a-9c11-3b5e7a0d9f21)). You create one by typing (( and searching, or with the Block reference command. Logseq then writes the matching id:: line under the target block so the reference keeps resolving.

Embeds are macros. {{embed [[Project Atlas]]}} pulls in a whole page, and {{embed ((uuid))}} pulls in a single block.

Page properties look a little like YAML front matter, but they aren't. There's no --- fence and no YAML parser involved, so tools that read Markdown front matter won't pick them up.

How to Use Logseq: A First Week Walkthrough

Here's how to use Logseq during your first week, with the Markdown each step produces.

  1. Create a graph. Pick an empty folder, or one that already holds notes. Logseq adds journals/, pages/ and assets/ to it.
  2. Write in today's journal. Type on the Journals page. Enter starts a new block, and Tab indents it under the block above.
  3. Link a page. Type [[ and a name, such as Project Atlas. Click the link to open that page, and anything you write there is saved in pages/.
  4. Add a property. Type :: to autocomplete a property name, then add a value such as type:: decision.
  5. Mark a task. Start a block with a marker, or press Ctrl+Enter (Cmd+Enter on Mac) to cycle through them. The default flavour is LATER, NOW, DONE, and settings switch it to TODO, DOING, DONE.
  6. Reference a block. Type ((, search for the block, and press Enter.
  7. Ask a question. Type /query to insert a simple query that collects matching blocks.

After those steps, one journal day might look like this on disk:

- Met [[Design Team]] about [[Project Atlas]]
	- They want the scope by Friday
	  type:: decision
- LATER Draft the [[Project Atlas]] scope
- DONE Book the meeting room
- Open tasks for Atlas
	- {{query (and [[Project Atlas]] (task LATER TODO))}}

In Logseq, the query block lists every LATER or TODO block that links to Project Atlas. A week in, open the Project Atlas page itself. Its linked references section gathers every journal block that mentioned it, which is the payoff for writing in the journal first and filing later. Linking instead of filing is also the idea behind the Zettelkasten method.

Can You Open Logseq Notes in Another Markdown Editor?

Yes, the files open anywhere, but only part of the structure survives. Plain text, nested bullets, bold, standard links and code blocks render as you'd expect. Logseq-specific syntax turns into literal text:

  • Page properties render as ordinary lines of text. A property under a bullet joins that bullet's text, so a reader sees collapsed:: true inside the kickoff notes item.
  • [[Page]] keeps its brackets unless the other app supports wikilinks.
  • A ((uuid)) reference becomes a meaningless string, because the text it points to lives in another block.
  • TODO and DONE are plain words. Logseq tasks don't use the - [ ] checkbox syntax, so no checkbox appears.
  • Embed and query macros show up raw, braces and all.

Here's a flat Logseq page pasted into a standard Markdown preview. The nesting from the first example is left out, because indented lines can't be pre-loaded here.

title:: Project Atlas
tags:: project, work

  • Kickoff call with [[Design Team]] #meeting
  • TODO Draft the scope document
  • DONE Book the meeting room
  • Budget figures are in ((6714b2c1-8f3e-4d2a-9c11-3b5e7a0d9f21))
  • See also {{embed [[Budget]]}}
  • Next step: send the agenda by ^^Friday^^
44 words293 characters9 lines
Markdown

The list and the bold text render. The two property lines show as one paragraph with a line break, and the page link, tag, task markers, block reference, embed and highlight stay as plain text. Our editor's preview doesn't render any Logseq-specific syntax, so treat it as a preview of what a typical Markdown app will show.

To read a full page file from your graph, open the .md file in the Markdown viewer, which renders it in your browser without uploading it.

Logseq Knowledge Management Habits That Keep Files Portable

A few habits make these files easier to carry elsewhere. We prefer keeping anything you'd hate to lose out of block references, because a bare UUID is useless outside Logseq. The rest follow from that:

  • Write important facts as text, and connect them with [[page]] links instead of ((uuid)) references.
  • Keep properties few and simple, since every other app shows them as raw key:: value lines.
  • Remember that namespaced pages become ___ filenames before you script against the folder.
  • Back up the graph folder like any other set of files. For a clean copy, the file version's Export graph menu offers Standard Markdown, which leaves out block properties.

What Is the Logseq DB Version, and What Happens to Your Markdown Files?

The Logseq DB version stores a graph in a SQLite database instead of a folder of Markdown files. On desktop, each DB graph lives in ~/logseq/graphs/GRAPH-NAME, with a db.sqlite file and an assets/ folder. The logseq/ config folder no longer exists there, and settings live inside the database.

It's still in testing. The project README labels the DB version beta, warns that data loss is possible, and suggests trying it on a test graph first. Logseq's 2.0 desktop releases on GitHub are DB-version betas, and 2.0.2 shipped in October 2026. The file-based code now lives in a separate repository, logseq/og.

Per Logseq's list of DB version changes, the main differences for file users are:

  • Markdown is the only supported syntax. Org-mode files are no longer supported.
  • Page properties aren't set in the first block anymore. You edit them from the page title instead.
  • Blocks and pages are both nodes, referenced with [[ ]]. Blocks no longer use (( )) for references.
  • Task markers become Status, Priority, Deadline and Scheduled properties, and you create tasks with commands such as /todo.
  • Heading and quote Markdown in a block is no longer visible or editable as text.
  • Whiteboards and slides are removed, and Excalidraw drawing and Zotero are no longer built in.

To move an existing graph, the DB version docs describe a DB Graph Importer under the three-dots menu, Import, then File to DB graph. It imports your Markdown files and remaps some task statuses, so LATER becomes Todo and NOW becomes Doing.

Getting Markdown back out works differently. The Export graph options include a SQLite file, a zip of SQLite plus assets, an EDN file, and standard Markdown without block properties. The docs say that Markdown is standard markdown, not Logseq markdown, and it's unlikely to ever carry timestamps or every property. EDN is the only export that captures all of a graph's data and stays editable, though the docs don't yet recommend it as your only backup.

Here's the honest limitation: a DB graph is no longer a folder you can open in any editor. If plain files on disk are why you picked the Logseq note taking app, keep a file graph or export to Markdown on a schedule. For DB graphs, the browser and desktop apps also offer automated backups that keep the last 12 copies.

Logseq Note Taking: Quick Answers

The Logseq note taking app makes sense once you know what it writes. A file graph holds dash-led blocks, key:: properties, page links and block references in plain .md files, while a DB graph keeps a SQLite file. Keep the parts you care about in ordinary Markdown and they'll survive any move. To see how a page reads outside Logseq, paste it into the editor and check the preview.