Skip to content

Enhancement (config): Add option $mediaLinkFormat to use wikilinks for media - #215

Open
El1as42 wants to merge 3 commits into
theohbrothers:masterfrom
El1as42:enhancement/config-add-option-medialinkformat-to-use-wikilinks-for-media
Open

El1as42 wants to merge 3 commits into
theohbrothers:masterfrom
El1as42:enhancement/config-add-option-medialinkformat-to-use-wikilinks-for-media

Conversation

@El1as42

@El1as42 El1as42 commented Oct 13, 2026 •

Copy link
Copy Markdown

Closes #213

Builds on #214 (its two commits are the first commits here), since media names must be unique within a notebook before they can be unique across notebooks. I'll rebase once it is merged, so that only the last commit remains.

Changes

  • New config option $mediaLinkFormat: 1 uses markdown links with relative paths (default, existing behavior), 2 uses wikilinks with only the file name, e.g. ![[mynotebook-mysection-mypage-image1.png]] for images and [[mynotebook-mysection-mypage-attachment.pdf]] for attachments.
  • Since wikilinks contain only the file name, media file names are unique across notebooks with 2:
    • Images and attachments are prefixed with the notebook, Section, and page path, i.e. the .md file's path within the notes destination.
    • # and ^ are replaced, since they have a special meaning in wikilinks.
    • Prefixes longer than 100 characters are shortened to their start (e.g. the notebook) and end (e.g. the page), cut at dashes if possible, with a hash of the full prefix in between, e.g. mynotebook-1a2b3c4d-mypage-image1.png. Attachment names longer than 150 characters are shortened, with a hash of the full name. So names stay unique, and media paths stay well below the path limit of 260 characters of Windows PowerShell 5.1, also after moving the notes to another folder. (Without this, a page nested three subpages deep in a notebook with a long name got image paths of 268 characters, and its images failed to be saved.)
  • Images are matched by their prefix, since it may contain any parentheses, e.g. f(g(x)) from nested ones, or a) from a page named a) Exercise. Wikilinks have no alternative text or pandoc link attributes, so these are omitted.
  • README.md and config.example.ps1 document the option.

Tests: a New-SectionGroupConversionConfig test for both values: media names are unique across the two fake notebooks, # and ^ are replaced, long subpage paths are shortened with a hash, attachments are prefixed and long attachment names shortened, and images (with alternative text and link attributes, two on one line, nested and unbalanced parentheses) and attachments are converted to wikilinks, or kept as markdown links with 1. Unit tests pass on Windows PowerShell 5.1 and PowerShell 7.0. In this repo's CI (run on my fork), all jobs that can currently run pass: Windows PowerShell 5.1 (windows-2022) and PowerShell 7.1 to 7.4. The other jobs currently fail for any PR, before checkout: the windows-2019 runner image was retired, and the PowerShell 6.0 to 7.0 container images are too old for actions/checkout (GLIBC_2.28' not found). Also tested on real notebook pages on Windows PowerShell 5.1, including a page nested three subpages deep in a notebook with a long name: images are converted to wikilinks, the linked files exist with these names, and the longest media path is 198 characters.

🤖 Generated with Claude Code

El1as42 and others added 3 commits October 13, 2026 18:28
…verwriting each other

With `$medialocation = 1` (default), the images of all of a notebook's pages are saved in the notebook's `media` folder, named after the page's Section and name, e.g. `mysection-mypage-image1.png`. So subpages with the same name (e.g. `Exercise` under two different pages) and identically-named pages of a Section got the same image names, and the images of one page overwrote the images of the other. Both pages then showed the same images.

Now image names include the page's parent pages and the postfix of identically-named pages, i.e. the `.md` file's path within the notebook, e.g. `mysection-mypage-mysubpage-image1.png`. Image names of first level pages that are not identically-named are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The error showed the result of the previous `New-Item` or `Move-Item` call (e.g. the `media` folder) instead of the image's destination path, making it impossible to tell which file name failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…for media

Media are linked with markdown links with relative paths, e.g. `![](../media/mysection-mypage-image1.png)`. Markdown viewers like Obsidian have to update these paths whenever notes or media are moved, which is fragile, especially for paths containing spaces or parentheses.

The new option `$mediaLinkFormat = 2` uses wikilinks with only the file name instead, e.g. `![[mynotebook-mysection-mypage-image1.png]]` for images and `[[mynotebook-mysection-mypage-attachment.pdf]]` for attachments. Such viewers find linked files anywhere by their name, so links don't break when moving notes or media. Since wikilinks contain only the file name, media file names must be unique across notebooks:
- Image and attachment names are prefixed with the notebook, Section, and page path, i.e. the `.md` file's path within the notes destination.
- `#` and `^` are replaced, since they have a special meaning in wikilinks.
- Prefixes longer than 100 characters are shortened to their start (e.g. the notebook) and end (e.g. the page), with a hash of the full prefix in between, and attachment names to 150 characters, with a hash of the full name. So names stay unique, and media paths stay well below the path limit of 260 characters on Windows, also after moving the notes to another folder.

Images are matched by their prefix, which may contain any parentheses. Wikilinks have no alternative text or pandoc link attributes, so these are omitted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@El1as42
El1as42 force-pushed the enhancement/config-add-option-medialinkformat-to-use-wikilinks-for-media branch from 4527627 to fb16de6 Compare October 14, 2026 08:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Option to use wikilinks for media

1 participant