[R&D] Architecture Research: Multi-Flavor Markdown Support

[YousefHadder]

1. Current State

markdown-plus.nvim is currently architected around GitHub Flavored Markdown (GFM). The logic for parsing, formatting, and handling syntax is tightly coupled to GFM rules. While this serves a large portion of users, it creates significant limitations for those working in other ecosystems.

2. Problem Statement

As the plugin grows, we are encountering friction due to this single-flavor design:

• Missing Syntax: Users of Obsidian, Typora, and other tools cannot use extended syntax features (e.g., ==highlight==, ++underline++, [[WikiLinks]]).
• Context Failures: Users of Quarto and LaTeX encounter bugs where the GFM-centric parser misinterprets valid syntax (e.g., pipes | inside math blocks being treated as table separators).
• Rigidity: There is no clean way to "switch modes" based on the project or file type.

3. Goal of this Research

The goal of this issue is to research and design a robust architecture that supports polymorphic markdown behavior. We aim to move from a "Hardcoded Logic" model to a "Capability-Based" model (likely an Adapter/Strategy pattern).

This is NOT an implementation plan yet. This issue serves as a central hub to:

1. Identify all architectural challenges.
2. Gather requirements for different flavors (Obsidian, Quarto, CommonMark, etc.).
3. Discuss design patterns (Adapters, Registry, Context Detection).
4. Formulate a roadmap for the eventual refactor.

We will use the comments below to document specific research areas, open questions, and design considerations.

[YousefHadder]

Key Research Areas & Questions

We need to investigate the following areas to build a complete picture:

A. Syntax Abstraction

• Question: How do we abstract regex patterns so they aren't hardcoded?
• Question: How do we handle "preferred" vs. "permissive" syntax? (e.g., parsing both _ and * for italic, but only generating *).
• Question: How do we handle features that exist in one flavor but not another (e.g., Callouts)?

B. Context Awareness (The "Parser" Problem)

• Question: To solve issues like [BUG] Format table removes content on a specific table structure #155 (LaTeX tables), we need to know "Where is the cursor?". Do we build a lightweight Lua parser, or rely on Tree-sitter?
• Consideration: Tree-sitter is powerful but adds a dependency that might behave differently across user configs. A lightweight internal state machine might be safer.

C. Configuration Design

• Question: Should flavors be rigid presets (flavor = "obsidian") or composable (flavor = { base="gfm", overrides={...} })?
• Question: How do we handle auto-detection? (File extensions, frontmatter, directory patterns).

D. Link Resolution

• Question: How do we abstract the logic for resolving [[WikiLinks]] vs standard [Links]()? This involves file system lookups that vary wildly between tools.

[YousefHadder]

Design Considerations & Constraints

As we design this, we must keep these constraints in mind:

1. Backward Compatibility: The default behavior MUST remain GFM. Existing users should not notice a change unless they opt-in.
2. Performance: The abstraction layer (Adapter lookup) must not introduce latency.
3. Type Safety: The new architecture must be fully typed with LuaCATS to maintain our development standards.
4. Testability: We need a strategy to run our test suite against multiple flavor configurations without duplicating every test file.

[YousefHadder]

References

Relevant Issues:

• Add ==highlight== and ++underline++ formatting #154 (Request for Highlight/Underline support)
• [BUG] Format table removes content on a specific table structure #155 (Bug with LaTeX pipes in tables)

External References (for research):

• CommonMark Spec
• GitHub Flavored Markdown Spec
• Obsidian Markdown Guide
• Quarto Markdown Basics