Neorg Decision Guide: Native Storage vs Markdown Interop

Decision & Constraints

When choosing Neorg as a note‑and‑task engine inside Neovim, the core decision is whether to rely on Neorg’s native .norg files or to export to Markdown for broader interoperability. The constraints that shape this choice are:

• Editor Scope – Neorg is a Neovim‑only plugin; it does not work in classic Vim or other editors.
• Parser Requirement – The dedicated Treesitter parser for norg must be installed; otherwise syntax highlighting and concealer features fail.
• File Locking – Neorg does not provide file locking; concurrent edits can silently overwrite data.
• Export Dependencies – PDF export requires external tools like pandoc and a TeX distribution.

Option Comparison

Feature	Native .norg Storage	Markdown Interop
Metadata Preservation	Full – custom todo states, priorities, tags, and internal links are stored verbatim.	Partial – only basic headings and plain text survive; custom states are lost unless re‑exported.
Task State Management	Direct – core.tasks and core.qol.todo_items work natively.	Indirect – tasks must be re‑parsed from Markdown; state changes are not reflected back to the source.
Cross‑Workspace Aggregation	Built‑in – core.dirman indexes all .norg files across mapped workspaces.	Manual – requires custom scripts to scan Markdown files.
Export Flexibility	Limited – only Neorg’s export modules (PDF, HTML) are available.	Broad – Markdown can be converted to PDF, DOCX, or HTML via external tools.
Editor Compatibility	Neovim only – requires norg Treesitter parser.	Any editor that supports Markdown.
Setup Complexity	Single Lua table; requires Treesitter.	Same Lua table plus core.export.markdown module.

Trade‑Off Summary

Use native .norg if:

• You need reliable task state persistence across sessions.
• All collaborators use Neovim and Neorg.
• You want built‑in workspace indexing and task aggregation.

Choose Markdown export when:

• You must share notes with users outside Neovim.
• You rely on external tooling for PDF or DOCX conversion.
• You prefer a widely supported file format for backups.

Concrete Implementation – Native Storage

1. Install Neorg and Dependencies

# Using lazy.nvim as the plugin manager
require('lazy').setup({
  { 'nvim-neorg/neorg',
    ft = 'norg',
    dependencies = {
      'nvim-treesitter/nvim-treesitter',
      'nvim-lua/plenary.nvim'
    },
    config = function()
      require('neorg').setup({
        load = {
          ['core.defaults'] = {},
          ['core.dirman'] = {
            config = {
              workspaces = {
                notes = '~/Documents/notes',
                tasks = '~/Documents/tasks'
              }
            }
          },
          ['core.qol.todo_items'] = {},
          ['core.tasks'] = {}
        }
      })
    end
  }
})

Run :TSInstall norg after Neovim starts to ensure the Treesitter parser is available.

2. Create a Workspace

Open Neovim and execute:

:Neorg workspace notes

This command changes the current directory to ~/Documents/notes and indexes all .norg files beneath it.

3. Add a Todo Item

In a new or existing .norg file, add:

- [ ] Write decision guide

Press the core.qol.todo_items default keybinding (usually Ctrl+Enter) to toggle the state. Verify the state change by re‑opening the file.

4. Aggregate Tasks Across Workspaces

Run:

:Neorg journal todolist

The output lists all pending tasks from both notes and tasks workspaces. Confirm the count matches the number of items you created.

Concrete Implementation – Markdown Interop

1. Enable the Markdown Export Module

require('neorg').setup({
  load = {
    ['core.export.markdown'] = {}
  }
})

2. Export a File

Open a .norg file and run:

:Neorg export markdown

The plugin generates a .md file in the same directory. Inspect the output to ensure headings and plain text are present.

3. Validate Export Integrity

To check that no syntax errors occurred during export, run:

:Neorg export markdown --check

Neorg will report any parsing issues. If the command exits cleanly, the Markdown file is considered valid.

Verification Checklist

1. Filetype Confirmation – Open a .norg file and run :set filetype? expecting filetype=norg.
2. Parser Status – Run :TSInstallInfo norg to confirm the parser is installed and no errors are reported.
3. Workspace Switching – Execute :Neorg workspace tasks and verify the working directory changes to ~/Documents/tasks.
4. Task Toggle – Create a todo, toggle its state, then use :Neorg journal todolist to ensure it appears.
5. Markdown Export – Export a file and open the resulting .md to confirm headings and plain text are present.

Practical Tips & Limitations

• Always pin a specific Neorg release in your plugin manager to avoid breaking changes.
• Keep the Treesitter parser updated; run :TSUpdate norg after Neovim updates.
• When collaborating across editors, consider maintaining a parallel Markdown copy and use core.export.markdown as a one‑way sync.
• Neorg does not support file locking; use a version control system (e.g., Git) to manage concurrent edits.
• Exporting to PDF requires pandoc and a TeX distribution; verify these are installed before attempting :Neorg export pdf.