بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
Markdown
How refac moves Markdown files, assets, and folders and keeps every link working, with no external tooling.
The Markdown backend is built into refac. It needs no language server and nothing to install. It moves Markdown files, the images and other assets they point at, and folders of both, and every link follows.
It also runs after the other languages. When a TypeScript, Python, Rust, Go, Dart, or Kotlin file or folder was moved, the Markdown links that point at it are fixed in the same command, so a README that points at src/app.py follows the move.
One engine does both jobs. It reads Markdown as CommonMark, changes only link destinations, writes them the way the author wrote them, plans the whole change before it touches the disk, and undoes everything if a step fails. These pages will inshallah show what it changes and where it stops.
What it does
When a path moves, refac:
- Updates incoming links: every Markdown file that points at the moved path gets its link destination rewritten.
- Recalculates outgoing links: relative links inside a moved Markdown file are measured from its new place.
- Fixes links to code: after a move in another language, links to the moved source files and folders are rewritten in the same command.
All three happen in one operation, and links between files that move together are left exactly as they were.
What can be moved
- Markdown files with the extensions
.md,.markdown, and.mdx, in any letter case. - Assets that Markdown points at: images (
png,jpg,jpeg,gif,svg,webp,avif,ico,bmp,tif,tiff,heic),pdf, audio and video (mp4,webm,mov,mp3,wav,ogg,flac), fonts (woff,woff2,ttf,otf), andzip. - Folders of Markdown and assets.
Formats that code reads or imports, such as json, yaml, toml, css, html, txt, and csv, are not assets. Moving one would leave references in code behind without a word, so refac reports it as skipped.
A folder is a document folder when it holds Markdown or assets and no code. A folder with TypeScript or Kotlin is moved by those backends, and a folder with any other code is refused with a message that says so.
refac move --project-path /my/docs --source-path guides --target-path handbook/guidesLink forms
| Form | Updated |
|---|---|
Inline links and images, with a #fragment, a ?query, or both | Yes |
| Reference definitions: collapsed, shortcut, titled, angle-bracket, and multi-line | Yes |
Destinations with spaces in angle brackets, and percent-encoded ones (My%20Notes.md) | Yes |
Raw HTML: href, src, poster, and every URL in a srcset | Yes |
| Links in table cells, lists, block quotes, and image links | Yes |
Links to a folder (docs/) | Yes |
Web addresses, mailto:, #anchors, and site-root paths (/docs/a.md) | Left alone |
Wiki-links ([[Page]]), MDX imports, front matter, code blocks | Not links to refac |
In this section
- Supported behavior: the link forms in detail, how a destination is written, the pass for links to code, and the safety rules.
- Limits and gaps: what is not a link to refac, the boundaries of a move, and style limits.
- Examples: before and after scenarios, plus a real command with its output.