From 611ebf43a57a6ec87e42a2d1be81a4d000b1fc0e Mon Sep 17 00:00:00 2001
From: Elias <schlosser.elias@web.de>
Date: Mon, 12 Oct 2026 21:09:55 +0200
Subject: [PATCH] Enhancement (config): Add option `$imageAltText` to remove
 image alternative text

For images in OneNote, the image alternative text is usually text recognized in the image by OneNote, which can be very long and contain characters like `|`, `[`, and `]`. Some markdown viewers like Obsidian then fail to render the image, and show the alternative text instead.

`$imageAltText = 2` removes the alternative text, e.g. `![some text](../media/image1.png)` becomes `![](../media/image1.png)`. The default `$imageAltText = 1` keeps the existing behavior.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ConvertOneNote2MarkDown-v2.Tests.ps1 | 50 ++++++++++++++++++++++++++++
 ConvertOneNote2MarkDown-v2.ps1       | 22 ++++++++++++
 config.example.ps1                   |  5 +++
 3 files changed, 77 insertions(+)

diff --git a/ConvertOneNote2MarkDown-v2.Tests.ps1 b/ConvertOneNote2MarkDown-v2.Tests.ps1
index 72d1ae7..73c896e 100644
--- a/ConvertOneNote2MarkDown-v2.Tests.ps1
+++ b/ConvertOneNote2MarkDown-v2.Tests.ps1
@@ -60,6 +60,7 @@ $prefixFolders = 1
 $medialocation = 1
 $conversion = 'markdown-simple_tables-multiline_tables-grid_tables+pipe_tables' # Default
 $headerTimestampEnabled = 1
+$imageAltText = 1
 $keepspaces = 1
 $keepescape = 1
 $newlineCharacter = 1
@@ -87,6 +88,7 @@ $newlineCharacter = 1
             $fakeUserInputs['medialocation']['value'] = ''
             $fakeUserInputs['conversion']['value'] = ''
             $fakeUserInputs['headerTimestampEnabled']['value'] = ''
+            $fakeUserInputs['imageAltText']['value'] = ''
             $fakeUserInputs['keepspaces']['value'] = ''
             $fakeUserInputs['keepescape']['value'] = ''
             $fakeUserInputs['newlineCharacter']['value'] = ''
@@ -1191,6 +1193,54 @@ Describe 'New-SectionGroupConversionConfig' -Tag 'Unit' {
             }
         }
 
+        It "Should honor config imageAltText" {
+            $fakeMarkdownContent = @'
+![](../media/p0.0-test-image1.png)
+
+![some \[text\] with \\ and (brackets)](../media/p0.0-test-image2.png){width="5.1875in" height="6.83in"}text ![more text](../media/p0.0-test-image3.png)
+
+[a link](https://example.com)
+'@
+            $expectedMarkdownContentRemoved = @'
+![](../media/p0.0-test-image1.png)
+
+![](../media/p0.0-test-image2.png){width="5.1875in" height="6.83in"}text ![](../media/p0.0-test-image3.png)
+
+[a link](https://example.com)
+'@
+            $params['Config']['keepescape']['value'] = 3
+            $params['Config']['newlineCharacter']['value'] = 1
+
+            foreach ($imageAltText in 1, 2) {
+                $params['Config']['imageAltText']['value'] = $imageAltText
+
+                $result = @( New-SectionGroupConversionConfig @params 6>$null )
+
+                # 15 pages from 'test' notebook, 15 pages from 'test2' notebook
+                $result.Count | Should -Be 48
+
+                foreach ($pageCfg in $result) {
+                    $content = $fakeMarkdownContent
+
+                    # Mutate
+                    foreach ($m in $pageCfg['mutations']) {
+                        foreach ($r in $m['replacements']) {
+                            $content = $content -replace $r['searchRegex'], $r['replacement']
+                        }
+                    }
+
+                    # Strip the heading
+                    $content = $content -replace '^# [^\n]*\n\nCreated: [^\n]*\n\nModified: [^\n]*\n\n---\n\n', ''
+
+                    if ($imageAltText -eq 1) {
+                        $content | Should -Be ($fakeMarkdownContent -replace '\r', '')
+                    }else {
+                        $content | Should -Be ($expectedMarkdownContentRemoved -replace '\r', '')
+                    }
+                }
+            }
+        }
+
         It "Should honor config keepspaces" {
             $params['Config']['keepspaces']['value'] = 1
 
diff --git a/ConvertOneNote2MarkDown-v2.ps1 b/ConvertOneNote2MarkDown-v2.ps1
index 3668cba..371d3e9 100644
--- a/ConvertOneNote2MarkDown-v2.ps1
+++ b/ConvertOneNote2MarkDown-v2.ps1
@@ -145,6 +145,16 @@ Default:
 Whether to include page timestamp and separator at top of document
 1: Include - Default
 2: Don't include
+'@
+            default = 1
+            value = 1
+            validateRange = 1,2
+        }
+        imageAltText = @{
+            description = @'
+Whether to keep the alternative text of images (e.g. ![alt text](image.png)). For images in OneNote, this is usually text recognized in the image by OneNote, which can be very long
+1: Keep - Default
+2: Remove
 '@
             default = 1
             value = 1
@@ -912,6 +922,18 @@ Function New-SectionGroupConversionConfig {
                                     }
                                 )
                             }
+                            if ($config['imageAltText']['value'] -eq 2) {
+                                @{
+                                    description = 'Remove image alternative text'
+                                    replacements = @(
+                                        @{
+                                            # E.g. '![some \[text\]](../media/somepage-image1.png)' -> '![](../media/somepage-image1.png)'. Pandoc escapes '\', '[', and ']' in alternative text, so this must happen before clearing '\' characters
+                                            searchRegex = '!\[(?:\\.|[^\\\]])*\]\('
+                                            replacement = '![]('
+                                        }
+                                    )
+                                }
+                            }
                             @{
                                 description = 'Add heading'
                                 replacements = @(
diff --git a/config.example.ps1 b/config.example.ps1
index 6077bdf..ba3dcb3 100644
--- a/config.example.ps1
+++ b/config.example.ps1
@@ -68,6 +68,11 @@ $conversion = 'markdown-simple_tables-multiline_tables-grid_tables+pipe_tables'
 # 2: Don't include
 $headerTimestampEnabled = 1
 
+# Whether to keep the alternative text of images (e.g. ![alt text](image.png)). For images in OneNote, this is usually text recognized in the image by OneNote, which can be very long
+# 1: Keep - Default
+# 2: Remove
+$imageAltText = 1
+
 # Whether to clear extra newlines between unordered (bullet) and ordered (numbered) list items, non-breaking spaces from blank lines, and `>` after unordered lists
 # 1: Clear - Default
 # 2: Don't clear