Wiki to Markdown Converter: JSPWiki Syntax Parsing and AST Transpilation

The Wiki to Markdown Converter is the core syntax transpilation engine within Wikantik responsible for translating legacy JSPWiki Creole markup (such as [LinkName], ! Heading, __bold__, and {{code}}) into standard CommonMark and GitHub Flavored Markdown (GFM).

This article details the lexer/parser pipeline, Abstract Syntax Tree (AST) node representations, link resolution algorithms, and edge-case handling for tables and math formatting.

1. Quick-Reference: Syntax Mapping Matrix

+-----------------------------------------------------------------------------------------+
|                               SYNTAX TRANSPILATION MAPPING                              |
+-----------------------------------------------------------------------------------------+
| Feature                | Legacy JSPWiki Markup             | Modern CommonMark / GFM    |
+------------------------+-----------------------------------+----------------------------+
| Top Heading            | `!!! Major Header`                | `# Major Header`           |
| Sub Heading            | `!! Sub Header`                   | `## Sub Header`            |
| Bold Text              | `__Bold Text__`                   | `**Bold Text**`            |
| Italic Text            | `''Italic Text''`                 | `*Italic Text*`            |
| Internal Wiki Link     | ``[PageName]``                      | `PageName`     |
| Labeled Wiki Link      | `[Custom Label|PageName]`         | `Custom Label` |
| Inline Code Block      | `{{code snippet}}`                | `` `code snippet` ``       |
| Fenced Code Block      | `{{{ java ... }}}`                | ```` ```java ... ``` ````  |
+-----------------------------------------------------------------------------------------+

2. Transpiler Architecture Pipeline

Transpiler Pipeline:
[ Raw JSPWiki Markup Stream ]
             |
             v
+-------------------------------------------------------+
| 1. Lexical Tokenizer                                  |
| - Identifies markup tokens: WIKI_LINK, HEADING_BANG,  |
|   CODE_FENCE, TABLE_PIPE, ESCAPED_CHARS               |
+-------------------------------------------------------+
             |
             v
+-------------------------------------------------------+
| 2. AST Construction (Node Tree)                       |
| - DocumentNode -> SectionNode -> ParagraphNode        |
| - Preserves inline formatting hierarchy               |
+-------------------------------------------------------+
             |
             v
+-------------------------------------------------------+
| 3. AST Transforms & Normalization                     |
| - Normalizes page slugs (removes spaces, enforces case)|
| - Escapes unescaped currency dollar signs (\$50K)      |
+-------------------------------------------------------+
             |
             v
[ Formatted CommonMark Output ]

3. Link Normalization and Currency Escaping Gotchas

Link Target Slugs: JSPWiki allowed spaces in links [My Page Name]. The transpiler maps this to My Page Name to maintain valid URL routing.
KaTeX Currency Collision: If JSPWiki text contained $100, unescaped conversion causes KaTeX math parser corruption. The AST transformer automatically inspects dollar signs and prepends backslashes (\$100).