How to Convert Wikilinks to Markdown in Zakirullin Files

The tomdlinks command-line utility transforms wiki-style [[links]] into standard Markdown [text](/path.md) links by scanning directories and performing regex replacement.

The zakirullin/files.md repository provides a lightweight toolkit for Markdown file management, including a dedicated utility to convert wikilinks to markdown format. This tool bridges the gap between Obsidian-style note-taking and standard Markdown compatibility, making it essential for users migrating notes to static site generators or GitHub-compatible formats.

The tomdlinks Utility

Located at cmd/tomdlinks/tomdlinks.go, the tomdlinks utility is a standalone Go program designed specifically for bulk conversion of wikilink syntax. It operates by building an index of all Markdown files in a target directory, then rewriting any [[filename]] references to proper relative links with URL-encoded paths.

How the Conversion Process Works

The utility follows a four-step pipeline to safely transform your documents without breaking existing references.

1. Directory Indexing

First, the scanner walks the supplied directory (defaulting to the current working directory) and catalogs every .md file. It creates a lookup map where keys are the base filenames (without the .md extension) and values are the relative paths to those files.

2. Pattern Detection

Using the regex pattern \[\[([^\[\]]+)\]\], the tool identifies all wikilink instances within each file. This pattern specifically targets double-bracketed content while ignoring nested brackets or malformed syntax.

3. Link Resolution

When a wikilink's inner text matches a key in the directory map, the utility constructs the replacement URL by:

• Prefixing the relative path with /
• URL-encoding spaces as %20
• Wrapping the result in standard Markdown link syntax [Title](/path)

4. File Updates

If replacements are found, the utility overwrites the original file with the converted content. To prevent accidental data loss, the tool supports a --dry-run flag that previews changes without writing to disk.

Usage Examples

Basic Conversion

Execute the utility against your notes directory:

go run ./cmd/tomdlinks .

Example output:

updated: notes/meeting.md
updated: projects/plan.md

Preview Mode with Dry-Run

Validate changes before committing them:

go run ./cmd/tomdlinks --dry-run .

This outputs:

would update: notes/meeting.md
would update: projects/plan.md

Transformation Example

Input file containing wikilinks:

Check the summary in [[meeting notes]] for details.

After conversion:

Check the summary in [meeting notes](/notes/meeting%20notes.md) for details.

Implementation Safety Features

The implementation in cmd/tomdlinks/tomdlinks.go prioritizes safety over aggressive matching. It only rewrites links that match existing filenames exactly, leaving unknown or ambiguous wikilinks untouched. This conservative approach prevents broken links in heterogeneous note collections where some references might point to external resources or not-yet-created files.

Summary

• The tomdlinks utility in cmd/tomdlinks/tomdlinks.go provides a dedicated tool to convert wikilinks to markdown format.
• It uses regex pattern \[\[([^\[\]]+)\]\] to identify wiki-style links and replaces them with relative Markdown links prefixed by /.
• The --dry-run flag enables safe previewing of changes before any file modification occurs.
• Only exact filename matches are converted; unknown wikilinks remain unchanged to prevent creating broken references.

Frequently Asked Questions

Where is the wikilink converter located in the repository?

The converter is implemented in cmd/tomdlinks/tomdlinks.go within the zakirullin/files.md repository. This standalone Go program can be executed directly using go run or compiled into a binary for repeated use across multiple projects.

Does the converter handle wikilinks that don't match existing files?

No. According to the source code analysis, the utility only converts wikilinks that exactly match the base name of an existing Markdown file in the scanned directory. Unknown links remain as raw [[text]] to avoid creating broken references to non-existent documents.

Can I preview changes before the utility modifies my files?

Yes. The utility supports a --dry-run flag that scans and reports which files would be updated without actually writing any changes to disk. This allows you to verify the conversion scope and accuracy before execution.

How does the tool handle filenames containing spaces?

The utility URL-encodes spaces as %20 in the generated paths. For example, a file named meeting notes.md becomes /meeting%20notes.md in the converted link, ensuring valid URL formatting while preserving the original display text inside the brackets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}