بِسْمِ ٱللَّهِ ٱلرَّحْمَـٰنِ ٱلرَّحِيمِ
Examples
Before and after examples of Markdown link rewrites, and a real folder move with its output.
These examples show the rewrites the backend performs. Each one names the move and shows the text before and after.
Incoming link update
Moving target.md to guides/target.md:
See [Target](./target.md).becomes:
See [Target](./guides/target.md).The ./ was there before, so it stays. A link written [Target](target.md) becomes [Target](guides/target.md).
Outgoing link recalculation
Moving target.md to guides/target.md:
[Sibling](./sibling.md)
[Leaf](./nested/leaf.md)becomes:
[Sibling](../sibling.md)
[Leaf](../nested/leaf.md)A path that climbs never gets ./.
Reference definitions, including a multi-line one
Moving target.md to guides/target.md:
See [Target][target] and [Other][other].
[target]: ./target.md#deep-dive "Deep Dive"
[other]:
target.mdbecomes:
See [Target][target] and [Other][other].
[target]: ./guides/target.md#deep-dive "Deep Dive"
[other]:
guides/target.mdThe usage text is unchanged. Only the definitions move.
Raw HTML
Moving docs/logo.png to assets/logo.png:
<img src="docs/logo.png" width="64">
<img srcset="docs/logo.png 1x, docs/logo@2x.png 2x" src="docs/logo.png">becomes:
<img src="assets/logo.png" width="64">
<img srcset="assets/logo.png 1x, docs/logo@2x.png 2x" src="assets/logo.png">Folders
Moving docs to documentation rewrites every link into the folder:
[Guide](docs/guide.md#install) [All docs](docs/) becomes:
[Guide](documentation/guide.md#install) [All docs](documentation/) Links between files inside the folder are not touched, because they moved together.
Spaces and percent-encoding
Moving docs to documentation:
[a](<docs/My Notes.md>) [b](docs/My%20Notes.md)becomes:
[a](<documentation/My Notes.md>) [b](documentation/My%20Notes.md)A link to code
Moving src/app.py to src/main.py with the Python backend, in the same command:
Start in [app](src/app.py#L10).becomes:
Start in [app](src/main.py#L10).Left alone
[External](file:///tmp/guide.md)
[Docs](https://example.com/guide)
[Anchor](#install)
`[code](docs/guide.md)`None of these change when docs/guide.md moves.
A real folder move
A small project with a README that links into guide/, and a guide/setup.md that links back:
README.md
guide/setup.md
guide/logo.pngPreview the move first:
refac move --dry-run --project-path . --source-path guide --target-path handbook/guide// Dry run: nothing was changed. 1 path would move, with 4 edits to update.
// Markdown results:
guide -> handbook/guide
// README.md (3 edits)
// guide/setup.md (1 edit)
// Note: Checked 2 Markdown files; updated 4 links in 2 files.
// Run the same command without --dry-run to apply the move.Run it without --dry-run, and the report starts with // Alhamdulillah 1 requested path was successfully refactored:. In README.md, [setup guide](guide/setup.md) is now [setup guide](handbook/guide/setup.md). In the moved setup.md, the link back to the README is ../../README.md, and its <img src="logo.png"> is untouched because the image moved with it. Your links should inshallah all resolve.
A target that exists
Moving a.md onto an existing docs2/a.md is refused, and nothing is changed:
// Nothing was moved.
// Failed:
// Markdown — Target already exists: /path/to/project/docs2/a.md
a.md -> docs2/a.mdThe exit code is 1.