Export-OneNoteMarkdown.ps1

<#
.SYNOPSIS
    Exports Microsoft OneNote notebooks to Markdown by reading the raw OneNote XML
    over the OneNote COM API.

.DESCRIPTION
    Drives the local OneNote 2016 desktop client via its COM interface:

        GetHierarchy()          -> notebook / section group / section / page tree
        GetPageContent()        -> per-page OneNote XML (piBasic, current schema)
        GetBinaryPageContent()  -> image bytes, fetched on demand per image

    The XML is converted to GitHub-Flavored Markdown in-process. Word and Pandoc are
    NOT used, so nothing is written to disk except the output tree, and collapsed
    (folded) paragraphs are included -- unlike the Publish()->.docx->Pandoc route.

    MUST run under Windows PowerShell 5.1. The OneNote COM interop fails under
    PowerShell 7.x with "Unexpected HRESULT has been returned from a call to a COM
    component"; support for the required Win32 GAC assembly was dropped after 7.0.

    Exports one notebook per run. Just run the script with no arguments and it lists
    the notebooks you have open in OneNote and asks which one to export.

.PARAMETER Notebook
    Name of the single notebook to export. Omit to be shown a numbered list to pick from.

.PARAMETER OutputRoot
    Destination folder. Defaults to an "out" folder next to this script.

.PARAMETER Force
    Re-export every page, even ones already up to date.

.PARAMETER RetryFailed
    Re-export only the pages the previous run reported a problem with.

.PARAMETER HighlightAs
    How highlighter-pen text is written: 'equals' (==text==, Obsidian/Orbit
    syntax, the default), 'html' (<mark>, for GitHub-bound output) or 'none'.

.EXAMPLE
    Right-click this file in File Explorer and choose "Run with PowerShell".

.EXAMPLE
    powershell.exe -NoProfile -File .\Export-OneNoteMarkdown.ps1 -Notebook "Sales Notebook"
#>
[CmdletBinding()]
param(
    [string]   $Notebook,
    [string]   $OutputRoot,
    [switch]   $Force,
    [switch]   $RetryFailed,
    [switch]   $IncludeFrontMatter,
    [switch]   $FlattenPageGroups,
    [ValidateSet('html', 'plus', 'bold', 'italic', 'none')]
    [string]   $UnderlineAs = 'html',
    [ValidateSet('html', 'equals', 'none')]
    [string]   $HighlightAs = 'equals',
    [switch]   $NoHydrateImages,
    [int]      $HydrateWaitMs = 1200,
    [int]      $HydrateMaxMs = 30000
)

Set-StrictMode -Version 2.0
$ErrorActionPreference = 'Stop'

# OneNote COM constants
$script:HS_PAGES    = 4  # HierarchyScope.hsPages
$script:PI_BASIC    = 0  # PageInfo.piBasic - no inline binary data
$script:XS_CURRENT  = 1  # XMLSchema, current

# Open/close pair used for underlined runs; overridden from -UnderlineAs at startup.
# Markdown has no underline syntax, so <u> is the default: it is the most portable
# option, working on GitHub, Jupyter and Obsidian without plugins.
$script:UnderlineMarkers = @('<u>', '</u>')

# Same idea for highlighted runs; overridden from -HighlightAs at startup.
# '==' is the Obsidian/Orbit syntax and the default; Orbit escapes raw HTML,
# so <mark> (the 'html' option) is only useful for GitHub-bound output.
$script:HighlightMarkers = @('==', '==')

# Tag 'symbol' values whose glyph is a checkbox. Tags using these become Markdown
# task-list items instead of an emoji prefix, taking their ticked state from the
# Tag element's 'completed' attribute.
#
# Note that 'completed' cannot be used to detect a checkbox: OneNote writes it on
# EVERY tag, including Important (a star) and Definition (a book), so keying off it
# would turn all of them into checkboxes. The glyph is the only reliable signal.
# Observed in these notebooks: 3 = To Do, 94 = Attendance and In Attendance.
$script:CheckboxTagSymbols = @{ '3' = $true; '94' = $true }

# Note tag name (lowercased) -> emoji prefix. Keyed by name because the numeric
# 'symbol' attribute is a glyph index that does not track tag meaning (the
# Important star, for instance, reports symbol 13). Checkbox glyphs are handled
# separately above: they become task-list items, not a prefix.
# Emoji are built from codepoints so this file stays ASCII-safe under PS 5.1.
$script:TagEmoji = @{
    'important'          = [char]::ConvertFromUtf32(0x2B50)    # star
    'question'           = [char]::ConvertFromUtf32(0x2753)    # red question mark
    'idea'               = [char]::ConvertFromUtf32(0x1F4A1)   # light bulb
    'critical'           = [char]::ConvertFromUtf32(0x2757)    # red exclamation
    'phone number'       = [char]::ConvertFromUtf32(0x1F4DE)   # telephone receiver
    'contact'            = [char]::ConvertFromUtf32(0x1F464)   # person silhouette
    'address'            = [char]::ConvertFromUtf32(0x1F3E0)   # house
    'web site to visit'  = [char]::ConvertFromUtf32(0x1F310)   # globe
    'remember for later' = [char]::ConvertFromUtf32(0x1F516)   # bookmark
    'definition'         = [char]::ConvertFromUtf32(0x1F4D6)   # open book
    'book to read'       = [char]::ConvertFromUtf32(0x1F4DA)   # books
}

#region Environment

function Assert-Environment {
    if ($PSVersionTable.PSVersion.Major -ne 5) {
        throw @"
This script must run under Windows PowerShell 5.1, not PowerShell $($PSVersionTable.PSVersion).
The OneNote COM interop fails on 7.x with 'Unexpected HRESULT'.

Re-run with:
  powershell.exe -NoProfile -File "$PSCommandPath" $($MyInvocation.UnboundArguments -join ' ')
"@
    }

    # OneNote runs at medium integrity as the logged-on user. COM activation and the
    # Running Object Table are partitioned by integrity level, and Office refuses to
    # launch elevated, so an elevated host cannot attach -- it just gets
    # 0x80080005 CO_E_SERVER_EXEC_FAILURE.
    $principal = New-Object Security.Principal.WindowsPrincipal(
        [Security.Principal.WindowsIdentity]::GetCurrent())
    if ($principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
        throw @"
This PowerShell window is running as Administrator. OneNote COM cannot be reached from an
elevated process -- it fails with 0x80080005 CO_E_SERVER_EXEC_FAILURE.

Close this window and open a NORMAL (non-Administrator) Windows PowerShell, then re-run.
This script does not need administrator rights.
"@
    }
}

function Get-OneNoteApp {
    # The COM server can report an unexpected HRESULT while cold. Retry briefly.
    for ($attempt = 1; $attempt -le 4; $attempt++) {
        try {
            return New-Object -ComObject OneNote.Application
        }
        catch {
            if ($attempt -eq 4) {
                throw "Could not attach to OneNote after $attempt attempts: $($_.Exception.Message)"
            }
            Write-Verbose "OneNote COM attach failed (attempt $attempt); retrying..."
            Start-Sleep -Seconds ($attempt * 2)
        }
    }
}

#endregion

#region Timestamps

function ConvertTo-UtcOrNull {
    # OneNote hands back ISO-8601 UTC, e.g. 2022-10-06T06:21:40.000Z
    param([string] $Value)
    if ([string]::IsNullOrWhiteSpace($Value)) { return $null }
    $parsed = [datetime]::MinValue
    $styles = [System.Globalization.DateTimeStyles]::AdjustToUniversal -bor
              [System.Globalization.DateTimeStyles]::AssumeUniversal
    if ([datetime]::TryParse($Value, [System.Globalization.CultureInfo]::InvariantCulture,
                             $styles, [ref]$parsed)) {
        # Windows cannot represent anything before 1601 on NTFS.
        if ($parsed.Year -ge 1601) { return $parsed }
    }
    return $null
}

function Set-ItemTimestamps {
    <#
        Stamps a file or folder with OneNote's own created/modified times so Explorer,
        SharePoint and Orbit show when the note was really written rather than when
        this export ran.
    #>
    param([string] $Path, $CreatedUtc, $ModifiedUtc)

    if ([string]::IsNullOrWhiteSpace($Path)) { return }
    if (-not $CreatedUtc -and -not $ModifiedUtc) { return }

    $wasReadOnly = $false
    $item = $null
    try {
        $item = Get-Item -LiteralPath $Path -Force -ErrorAction Stop

        # Copy-Item inherits the source's read-only flag, and under .NET Framework
        # (Windows PowerShell 5.1) setting a timestamp on a read-only file throws
        # Access Denied. Lift the flag for the write, then put it back.
        if ($item -is [System.IO.FileInfo] -and $item.IsReadOnly) {
            $item.IsReadOnly = $false
            $wasReadOnly = $true
        }

        if ($CreatedUtc)  { $item.CreationTimeUtc  = $CreatedUtc }
        if ($ModifiedUtc) { $item.LastWriteTimeUtc = $ModifiedUtc }
    }
    catch {
        Write-Warning "Could not set the date on '$Path': $($_.Exception.Message)"
    }
    finally {
        if ($wasReadOnly -and $item) {
            try { $item.IsReadOnly = $true } catch { }
        }
    }
}

#endregion

#region Naming helpers

function Get-SafeName {
    param(
        [string]    $Name,
        [hashtable] $Used,
        [int]       $MaxLength = 120
    )

    if ([string]::IsNullOrWhiteSpace($Name)) { $Name = 'Untitled' }

    $safe = $Name
    foreach ($c in [System.IO.Path]::GetInvalidFileNameChars()) {
        $safe = $safe.Replace($c, '-')
    }
    # Collapse runs of whitespace/dashes and trim characters Windows dislikes at the ends.
    $safe = ($safe -replace '\s+', ' ').Trim().Trim('.', ' ', '-')
    if ($safe.Length -gt $MaxLength) { $safe = $safe.Substring(0, $MaxLength).Trim() }
    if ([string]::IsNullOrWhiteSpace($safe)) { $safe = 'Untitled' }

    # Reserved DOS device names.
    if ($safe -match '^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$') { $safe = "_$safe" }

    if ($null -eq $Used) { return $safe }

    $candidate = $safe
    $n = 2
    while ($Used.ContainsKey($candidate.ToLowerInvariant())) {
        $candidate = "$safe-$n"
        $n++
    }
    $Used[$candidate.ToLowerInvariant()] = $true
    return $candidate
}

function Get-Slug {
    param([string] $Text)
    $s = ($Text -replace '[^A-Za-z0-9]+', '-').Trim('-').ToLowerInvariant()
    if ([string]::IsNullOrWhiteSpace($s)) { $s = 'page' }
    if ($s.Length -gt 40) { $s = $s.Substring(0, 40).Trim('-') }
    return $s
}

#endregion

#region Inline text conversion

function ConvertFrom-HtmlEntities {
    # OneNote sometimes double-encodes, storing "&amp;#128222;" so a single decode
    # leaves a visible "&#128222;". Decode until it stops changing.
    param([string] $Text)
    for ($i = 0; $i -lt 3; $i++) {
        $next = [System.Net.WebUtility]::HtmlDecode($Text)
        if ($next -eq $Text) { break }
        $Text = $next
    }

    # .NET Framework's HtmlDecode only handles code points that fit in a char, so
    # numeric references above U+FFFF (emoji, almost always) come back untouched.
    # Convert those by hand via surrogate pairs.
    if ($Text.Contains('&#')) {
        $Text = [regex]::Replace($Text, '&#([xX][0-9A-Fa-f]+|[0-9]+);', {
            param($m)
            $raw = $m.Groups[1].Value
            try {
                if ($raw[0] -eq 'x' -or $raw[0] -eq 'X') {
                    $cp = [Convert]::ToInt32($raw.Substring(1), 16)
                } else {
                    $cp = [int]$raw
                }
                if ($cp -gt 0 -and $cp -le 0x10FFFF) { return [char]::ConvertFromUtf32($cp) }
            }
            catch { }
            return $m.Value
        })
    }
    return $Text
}

function ConvertTo-EscapedText {
    param([string] $Text)
    if ([string]::IsNullOrEmpty($Text)) { return '' }
    # Conservative: only characters that would otherwise be read as Markdown syntax.
    # Underscore is deliberately left alone -- GFM has no intra-word emphasis, and
    # escaping it mangles identifiers like My_Project.
    $t = $Text -replace '\\', '\\'
    $t = $t -replace '([`\*\[\]])', '\$1'
    $t = $t -replace '<', '\<'
    return $t
}

function Get-HighlightBucket {
    <#
        Maps a CSS colour (name or #hex) to the nearest Orbit highlight bucket:
        yellow, green, blue, red, purple or orange. Anything unparseable or
        washed-out (greys) falls back to yellow, the default highlighter.
    #>
    param([string] $Color)

    $named = @{
        'yellow' = '#ffff00'; 'gold'     = '#ffd700'; 'lime'    = '#00ff00'
        'green'  = '#008000'; 'olive'    = '#808000'; 'teal'    = '#008080'
        'aqua'   = '#00ffff'; 'cyan'     = '#00ffff'; 'blue'    = '#0000ff'
        'navy'   = '#000080'; 'darkblue' = '#00008b'; 'skyblue' = '#87ceeb'
        'red'    = '#ff0000'; 'darkred'  = '#8b0000'; 'maroon'  = '#800000'
        'pink'   = '#ffc0cb'; 'fuchsia'  = '#ff00ff'; 'magenta' = '#ff00ff'
        'purple' = '#800080'; 'violet'   = '#ee82ee'; 'orange'  = '#ffa500'
        'darkorange' = '#ff8c00'
    }
    $c = $Color.Trim().ToLowerInvariant()
    if ($named.ContainsKey($c)) { $c = $named[$c] }

    if ($c -match '^#([0-9a-f])([0-9a-f])([0-9a-f])$') {
        $c = '#' + $Matches[1] + $Matches[1] + $Matches[2] + $Matches[2] + $Matches[3] + $Matches[3]
    }
    if ($c -notmatch '^#[0-9a-f]{6}$') { return 'yellow' }

    $r = [Convert]::ToInt32($c.Substring(1, 2), 16)
    $g = [Convert]::ToInt32($c.Substring(3, 2), 16)
    $b = [Convert]::ToInt32($c.Substring(5, 2), 16)

    $max = [Math]::Max($r, [Math]::Max($g, $b))
    $min = [Math]::Min($r, [Math]::Min($g, $b))
    if (($max - $min) -lt 30) { return 'yellow' }   # grey-ish: no real hue

    $hue = 0.0
    $d = [double]($max - $min)
    if     ($max -eq $r) { $hue = 60.0 * ((($g - $b) / $d) % 6) }
    elseif ($max -eq $g) { $hue = 60.0 * ((($b - $r) / $d) + 2) }
    else                 { $hue = 60.0 * ((($r - $g) / $d) + 4) }
    if ($hue -lt 0) { $hue += 360 }

    if ($hue -lt 15 -or $hue -ge 330) { return 'red' }
    if ($hue -lt 45)                  { return 'orange' }
    if ($hue -lt 75)                  { return 'yellow' }
    if ($hue -lt 165)                 { return 'green' }
    if ($hue -lt 255)                 { return 'blue' }
    return 'purple'
}

function Get-SpanMarkers {
    <#
        Maps a CSS style attribute to Markdown open/close marker pairs.
        Returns an array of two-element arrays: @(open, close).
    #>
    param([string] $Style)

    $markers = @()
    if ([string]::IsNullOrEmpty($Style)) { return ,$markers }
    $s = $Style.ToLowerInvariant()
    $have = @{}

    if ($s -match 'font-weight\s*:\s*bold' -and -not $have['**']) {
        $markers += ,@('**', '**'); $have['**'] = $true
    }
    if ($s -match 'font-style\s*:\s*italic' -and -not $have['*']) {
        $markers += ,@('*', '*'); $have['*'] = $true
    }
    if ($s -match 'text-decoration\s*:[^;]*line-through' -and -not $have['~~']) {
        $markers += ,@('~~', '~~'); $have['~~'] = $true
    }
    # Markdown has no underline. Whatever we map it to must not be emitted twice when
    # the run is also bold/italic, or the doubled markers render literally.
    if ($s -match 'text-decoration\s*:[^;]*underline') {
        $u = $script:UnderlineMarkers
        if ($u -and -not $have[$u[0]]) { $markers += ,$u; $have[$u[0]] = $true }
    }
    # Highlighter pen arrives as 'background:lime;mso-highlight:lime' (any colour).
    # The property-start anchor keeps 'mso-highlight' itself from matching, but it
    # is used as a fallback when no background property is present.
    $bg = $null
    if ($s -match '(?:^|;)\s*background(?:-color)?\s*:\s*([^;]+)') { $bg = $Matches[1].Trim() }
    elseif ($s -match '(?:^|;)\s*mso-highlight\s*:\s*([^;]+)')     { $bg = $Matches[1].Trim() }
    if ($bg -and $bg -notmatch '^(transparent|none|white|window|auto|automatic|#fff|#ffffff)$') {
        $h = $script:HighlightMarkers
        if ($h -and -not $have[$h[1]]) {
            if ($h[0] -eq '==') {
                # Orbit colour-codes highlights: =g= green, =b= blue, =r= red,
                # =p= purple, =o= orange; plain == is yellow.
                $open = switch (Get-HighlightBucket $bg) {
                    'green'  { '=g=' }
                    'blue'   { '=b=' }
                    'red'    { '=r=' }
                    'purple' { '=p=' }
                    'orange' { '=o=' }
                    default  { '==' }
                }
                $markers += ,@($open, '==')
            }
            else {
                $markers += ,$h
            }
            $have[$h[1]] = $true
        }
    }

    # Unary comma: stop PowerShell unrolling a single marker pair into two strings.
    return ,$markers
}

function Format-LinkTarget {
    # onenote: URLs routinely contain unescaped parentheses and spaces, which would
    # terminate a Markdown link early. Angle brackets make them safe.
    param([string] $Href)
    if ($Href -match '[()\s]') { return "<$Href>" }
    return $Href
}

function Convert-TextRun {
    <#
        Converts the CDATA payload of a <one:T> element to Markdown.
        The complete inline surface OneNote emits is three tags: span, a, br.
    #>
    param([string] $Raw)

    if ([string]::IsNullOrEmpty($Raw)) { return '' }

    $sb        = New-Object System.Text.StringBuilder
    $stack     = New-Object System.Collections.ArrayList
    $tokens    = [regex]::Split($Raw, '(<[^>]*>)')

    foreach ($token in $tokens) {
        if ([string]::IsNullOrEmpty($token)) { continue }

        if ($token[0] -ne '<') {
            # Literal text.
            $decoded = ConvertFrom-HtmlEntities $token
            $decoded = $decoded -replace " ", ' '   # nbsp
            # GFM emphasis is ignored when the marker touches whitespace ('** text**'),
            # and OneNote spans routinely include their surrounding spaces. So span
            # markers are deferred: written here, just before the first non-blank text
            # inside the span, with any leading whitespace emitted ahead of them.
            if ($decoded.Trim().Length -gt 0) {
                if ($decoded -match '^(\s+)') {
                    [void]$sb.Append($Matches[1])
                    $decoded = $decoded.Substring($Matches[1].Length)
                }
                foreach ($frame in $stack) {
                    if ($frame.Kind -eq 'span' -and -not $frame.Opened) {
                        foreach ($m in $frame.Markers) { [void]$sb.Append($m[0]) }
                        $frame.Opened = $true
                    }
                }
            }
            [void]$sb.Append((ConvertTo-EscapedText $decoded))
            continue
        }

        if ($token -match '^<\s*br\s*/?\s*>$') {
            [void]$sb.Append("`n")
            continue
        }

        if ($token -match '^<\s*span\b') {
            $style = ''
            if ($token -match 'style\s*=\s*"([^"]*)"')   { $style = $Matches[1] }
            elseif ($token -match "style\s*=\s*'([^']*)'") { $style = $Matches[1] }

            $markers = Get-SpanMarkers $style
            # Opened stays false until the span produces visible text (see above);
            # a marker-less span is born 'opened' so closing it is a no-op.
            [void]$stack.Add(@{ Kind = 'span'; Markers = $markers; Opened = ($markers.Count -eq 0) })
            continue
        }

        if ($token -match '^<\s*/\s*span\s*>$') {
            $frame = $null
            for ($i = $stack.Count - 1; $i -ge 0; $i--) {
                if ($stack[$i].Kind -eq 'span') { $frame = $stack[$i]; $stack.RemoveAt($i); break }
            }
            if ($frame -and $frame.Opened -and $frame.Markers.Count -gt 0) {
                # Shuffle trailing whitespace outside the close marker ('**foo **' -> '**foo** ').
                $tail = ''
                while ($sb.Length -gt 0 -and [char]::IsWhiteSpace($sb[$sb.Length - 1])) {
                    $tail = [string]$sb[$sb.Length - 1] + $tail
                    $sb.Length--
                }
                for ($i = $frame.Markers.Count - 1; $i -ge 0; $i--) {
                    [void]$sb.Append($frame.Markers[$i][1])
                }
                [void]$sb.Append($tail)
            }
            continue
        }

        if ($token -match '^<\s*a\b') {
            $href = ''
            if ($token -match 'href\s*=\s*"([^"]*)"')   { $href = $Matches[1] }
            elseif ($token -match "href\s*=\s*'([^']*)'") { $href = $Matches[1] }
            $href = ConvertFrom-HtmlEntities $href
            [void]$sb.Append('[')
            [void]$stack.Add(@{ Kind = 'a'; Href = $href })
            continue
        }

        if ($token -match '^<\s*/\s*a\s*>$') {
            $frame = $null
            for ($i = $stack.Count - 1; $i -ge 0; $i--) {
                if ($stack[$i].Kind -eq 'a') { $frame = $stack[$i]; $stack.RemoveAt($i); break }
            }
            if ($frame) {
                [void]$sb.Append('](' + (Format-LinkTarget $frame.Href) + ')')
            } else {
                [void]$sb.Append(']')
            }
            continue
        }

        # Any other tag: drop it, keep the text.
    }

    # Close anything OneNote left dangling.
    for ($i = $stack.Count - 1; $i -ge 0; $i--) {
        $frame = $stack[$i]
        if ($frame.Kind -eq 'a') {
            [void]$sb.Append("]($($frame.Href))")
        } elseif ($frame.Opened) {
            for ($j = $frame.Markers.Count - 1; $j -ge 0; $j--) {
                [void]$sb.Append($frame.Markers[$j][1])
            }
        }
    }

    $out = $sb.ToString()

    # Safety net: drop emphasis that ended up wrapping only whitespace, which would
    # render literally. The italic rule needs \s+ (not \s*) or it would eat the two
    # stars of every legitimate '**' bold marker.
    $out = $out -replace '\*\*(\s+)\*\*', '$1'
    $out = $out -replace '~~(\s+)~~', '$1'
    $out = $out -replace '\+\+(\s+)\+\+', '$1'
    $out = $out -replace '<u>(\s*)</u>', '$1'
    $out = $out -replace '<mark>(\s*)</mark>', '$1'
    $out = $out -replace '(?<!\*)\*(\s+)\*(?!\*)', '$1'

    return $out
}

#endregion

#region Block conversion

function Get-ChildElements {
    param($Node)
    $result = @()
    if ($null -eq $Node) { return $result }
    foreach ($c in $Node.ChildNodes) {
        if ($c.NodeType -eq [System.Xml.XmlNodeType]::Element) { $result += $c }
    }
    return ,$result
}

function Get-Attr {
    param($Node, [string] $Name, [string] $Default = '')
    if ($null -eq $Node) { return $Default }
    $a = $Node.Attributes.GetNamedItem($Name)
    if ($null -eq $a) { return $Default }
    return $a.Value
}

function Convert-Table {
    param($Table, $Ctx, [int] $Depth)

    # First pass keeps each cell as block content (an array of lines), because
    # the table might turn out to be a layout wrapper that we unwrap instead.
    $rows = @()
    foreach ($child in (Get-ChildElements $Table)) {
        if ($child.LocalName -ne 'Row') { continue }
        $cells = @()
        foreach ($cell in (Get-ChildElements $child)) {
            if ($cell.LocalName -ne 'Cell') { continue }
            $inner = @()
            foreach ($cc in (Get-ChildElements $cell)) {
                if ($cc.LocalName -eq 'OEChildren') {
                    $inner += Convert-OeChildren -OeChildren $cc -Ctx $Ctx -Depth 0
                }
            }
            $cells += ,@($inner)
        }
        if ($cells.Count -gt 0) { $rows += ,$cells }
    }

    if ($rows.Count -eq 0) { return @() }

    $width = 0
    foreach ($r in $rows) { if ($r.Count -gt $width) { $width = $r.Count } }

    # A one-column table is a layout container, not data -- pasted emails wrap
    # their entire body in one. GFM cannot nest block content (headings, lists,
    # other tables) inside a cell anyway, so unwrap: emit each row's content as
    # ordinary blocks. Nested real tables inside then render as proper tables.
    if ($width -eq 1) {
        $out = @()
        foreach ($r in $rows) {
            $lines = @($r[0])
            if ((($lines -join '').Trim()).Length -eq 0) { continue }
            if ($out.Count -gt 0) { $out += '' }
            $out += $lines
        }
        return $out
    }

    # A real (multi-column) table: flatten each cell to a single line, since GFM
    # cells cannot contain newlines, and escape any pipes from nested content.
    $flatRows = @()
    foreach ($r in $rows) {
        $cells = @()
        foreach ($c in $r) {
            $text = (($c -join "`n") -replace '\r', '').Trim()
            $text = ($text -split "`n" | Where-Object { $_.Trim().Length -gt 0 }) -join '<br>'
            $text = $text -replace '\|', '\|'
            $cells += $text
        }
        $flatRows += ,$cells
    }
    $rows = $flatRows

    function Format-Row {
        param([string[]] $Cells, [int] $Width)
        $padded = @($Cells) + @('') * ($Width - $Cells.Count)
        return '| ' + (($padded | ForEach-Object { $_ }) -join ' | ') + ' |'
    }

    $hasHeader = (Get-Attr $Table 'hasHeaderRow' 'false') -eq 'true'
    $lines = @()

    if ($hasHeader) {
        $lines += Format-Row -Cells $rows[0] -Width $width
        $lines += '|' + (' --- |' * $width)
        for ($i = 1; $i -lt $rows.Count; $i++) {
            $lines += Format-Row -Cells $rows[$i] -Width $width
        }
    }
    else {
        # GFM requires a header row, so emit an empty one.
        $lines += '|' + ('  |' * $width)
        $lines += '|' + (' --- |' * $width)
        foreach ($r in $rows) { $lines += Format-Row -Cells $r -Width $width }
    }

    $indent = ' ' * (2 * $Depth)
    return ($lines | ForEach-Object { "$indent$_" })
}

function Copy-EmbeddedFile {
    <#
        Copies an embedded file (InsertedFile / MediaFile) into the page's media
        folder. The original path (pathSource) is tried first, then OneNote's local
        cache copy (pathCache) -- the file's bytes stored under a .bin name, and
        usually the only copy present for notebooks authored on another machine.
    #>
    param($Node, $Ctx)

    $name = Get-Attr $Node 'preferredName' 'attachment'
    $safe = Get-SafeName -Name $name -Used $null

    foreach ($src in @((Get-Attr $Node 'pathSource'), (Get-Attr $Node 'pathCache'))) {
        if ([string]::IsNullOrWhiteSpace($src)) { continue }
        if (-not (Test-Path -LiteralPath $src)) { continue }
        try {
            $mediaDir = Join-Path $Ctx.PageDir 'media'
            if (-not (Test-Path -LiteralPath $mediaDir)) {
                New-Item -ItemType Directory -Path $mediaDir -Force | Out-Null
            }
            $attachTarget = Join-Path $mediaDir $safe
            Copy-Item -LiteralPath $src -Destination $attachTarget -Force
            Set-ItemTimestamps -Path $attachTarget -CreatedUtc $Ctx.CreatedUtc -ModifiedUtc $Ctx.ModifiedUtc
            $Ctx.FilesSaved++
            return [pscustomobject]@{ Name = $name; Link = "[$name](media/$($safe -replace ' ', '%20'))"; Copied = $true }
        }
        catch {
            $Ctx.Warnings.Add("attachment-copy-failed:$safe") | Out-Null
        }
    }
    return [pscustomobject]@{ Name = $name; Link = ''; Copied = $false }
}

function Save-PageImage {
    param($Image, $Ctx)

    $callback = $null
    foreach ($c in (Get-ChildElements $Image)) {
        if ($c.LocalName -eq 'CallbackID') { $callback = $c; break }
    }

    $format = Get-Attr $Image 'format' 'png'
    if ([string]::IsNullOrWhiteSpace($format)) { $format = 'png' }
    $alt = Get-Attr $Image 'alt' ''

    if ($null -eq $callback) {
        $Ctx.Warnings.Add('image-without-callback') | Out-Null
        return "> [!NOTE] An image on this page could not be extracted (no callback ID)."
    }

    $Ctx.ImageIndex++
    $fileName = '{0}-{1:d2}.{2}' -f $Ctx.PageSlug, $Ctx.ImageIndex, $format
    $mediaDir = Join-Path $Ctx.PageDir 'media'
    $fullPath = Join-Path $mediaDir $fileName

    try {
        if (-not (Test-Path -LiteralPath $mediaDir)) {
            New-Item -ItemType Directory -Path $mediaDir -Force | Out-Null
        }
        [ref]$b64 = ''
        $Ctx.App.GetBinaryPageContent($Ctx.PageId, (Get-Attr $callback 'callbackID'), $b64)
        $bytes = [Convert]::FromBase64String($b64.Value)
        [System.IO.File]::WriteAllBytes($fullPath, $bytes)
        Set-ItemTimestamps -Path $fullPath -CreatedUtc $Ctx.CreatedUtc -ModifiedUtc $Ctx.ModifiedUtc
        $Ctx.ImagesSaved++
    }
    catch {
        $Ctx.Warnings.Add("image-failed:$fileName") | Out-Null
        Write-Verbose "Image extraction failed for $fileName : $($_.Exception.Message)"
        return "> [!NOTE] An image on this page could not be extracted."
    }

    # OneNote stuffs its OCR output into @alt as "Machine generated alternative text:"
    # followed by the entire scraped page. Useless as alt text, so fall back to the title.
    $altText = $alt
    if ($altText -match '^\s*Machine generated alternative text\s*:') { $altText = '' }
    if ([string]::IsNullOrWhiteSpace($altText)) { $altText = $Ctx.PageTitle }
    $altText = (($altText -replace '[\[\]]', '') -replace '\s+', ' ').Trim()
    if ($altText.Length -gt 120) { $altText = $altText.Substring(0, 117).TrimEnd() + '...' }

    return "![$altText](media/$fileName)"
}

function Convert-Oe {
    param($Oe, $Ctx, [int] $Depth)

    $out    = @()
    $parts  = @()
    $blocks = @()

    $styleName  = ''
    $quickIndex = Get-Attr $Oe 'quickStyleIndex' ''
    if ($quickIndex -ne '' -and $Ctx.QuickStyles.ContainsKey($quickIndex)) {
        $styleName = $Ctx.QuickStyles[$quickIndex]
    }

    $listMarker = ''
    $checkbox   = ''
    $tagPrefix  = ''
    $sawText    = $false

    # User-enlarged text is a heading in all but name: quickStyleIndex stays 'p' and
    # the size lands in a font-size on the OE or its T children. Track the largest.
    $fontSize = 0.0
    if ((Get-Attr $Oe 'style') -match 'font-size\s*:\s*([\d.]+)\s*pt') {
        $fontSize = [double]$Matches[1]
    }

    foreach ($child in (Get-ChildElements $Oe)) {
        switch ($child.LocalName) {

            'T' {
                $sawText = $true
                if ((Get-Attr $child 'style') -match 'font-size\s*:\s*([\d.]+)\s*pt') {
                    $ts = [double]$Matches[1]
                    if ($ts -gt $fontSize) { $fontSize = $ts }
                }
                $parts += Convert-TextRun $child.InnerText
            }

            'List' {
                foreach ($l in (Get-ChildElements $child)) {
                    if ($l.LocalName -eq 'Bullet') { $listMarker = '-' }
                    elseif ($l.LocalName -eq 'Number') { $listMarker = '1.' }
                }
            }

            'Tag' {
                $idx = Get-Attr $child 'index' ''
                if ($Ctx.TagDefs.ContainsKey($idx)) {
                    $def = $Ctx.TagDefs[$idx]
                    if ($script:CheckboxTagSymbols[$def.Symbol]) {
                        $done = (Get-Attr $child 'completed' 'false') -eq 'true'
                        if ($done) { $checkbox = '- [x]' } else { $checkbox = '- [ ]' }
                    }
                    else {
                        $emoji = $null
                        if ($def.Name) { $emoji = $script:TagEmoji[$def.Name.ToLowerInvariant()] }
                        if ($emoji) {
                            $tagPrefix = "$emoji "
                        }
                        elseif ($def.Name) {
                            # Custom tags with no emoji mapping keep a readable label.
                            $tagPrefix = "``$($def.Name.ToUpperInvariant())`` "
                        }
                    }
                    if ($def.Name) { $Ctx.PageTags[$def.Name] = $true }
                }
            }

            'Image' {
                # Indent to the enclosing list depth, otherwise a column-0 image
                # terminates the surrounding list and the items after it get
                # reinterpreted as an indented code block.
                $blocks += ''
                $blocks += (' ' * (2 * $Depth)) + (Save-PageImage -Image $child -Ctx $Ctx)
            }

            'Table' {
                $blocks += ''
                $blocks += (Convert-Table -Table $child -Ctx $Ctx -Depth $Depth)
            }

            'OEChildren' {
                # Indentation only means 'nested list' in Markdown when the parent is
                # itself a list item. Under a heading, plain paragraph or empty wrapper
                # OE, 4+ leading spaces turn the children into an indented code block,
                # so those children stay at the current depth instead.
                $childDepth = $Depth
                if ($listMarker -or $checkbox) { $childDepth = $Depth + 1 }
                $blocks += Convert-OeChildren -OeChildren $child -Ctx $Ctx -Depth $childDepth
            }

            'InkDrawing' {
                $Ctx.Warnings.Add('ink-not-exported') | Out-Null
                $blocks += ''
                $blocks += '> [!WARNING] Handwritten ink on this page was not exported.'
            }

            'InkWord' {
                $Ctx.Warnings.Add('ink-not-exported') | Out-Null
            }

            'InsertedFile' {
                $f = Copy-EmbeddedFile -Node $child -Ctx $Ctx
                if ($f.Copied) {
                    $parts += $f.Link
                } else {
                    $Ctx.Warnings.Add("attachment-missing:$($f.Name)") | Out-Null
                    $parts += "``[attachment: $($f.Name)]``"
                }
            }

            'MediaFile' {
                $f = Copy-EmbeddedFile -Node $child -Ctx $Ctx
                if ($f.Copied) {
                    $parts += $f.Link
                } else {
                    $Ctx.Warnings.Add("mediafile-not-exported:$($f.Name)") | Out-Null
                    $parts += "``[embedded media: $($f.Name)]``"
                }
            }
        }
    }

    $text   = ($parts -join '').Trim()
    $indent = ' ' * (2 * $Depth)

    if ($text.Length -gt 0) {
        if ($styleName -match '^h([1-6])$') {
            # The page title owns '#', so shift OneNote headings down one level.
            $level  = [int]$Matches[1] + 1
            if ($level -gt 6) { $level = 6 }
            $out += ('#' * $level) + ' ' + $tagPrefix + ($text -replace "`n", ' ')
        }
        elseif ($fontSize -ge 14 -and -not $listMarker -and -not $checkbox) {
            # Enlarged plain text becomes a heading. OneNote's own scale: h1 = 16pt,
            # h2 = 14pt, body = 11-12pt, so 14pt is the smallest safe cutoff.
            $level = if ($fontSize -ge 16) { 2 } else { 3 }
            $t = $text -replace "`n", ' '
            # A heading is already emphasised by its size; drop redundant full-wrap bold.
            if ($t -match '^\*\*([^*]+)\*\*$') { $t = $Matches[1] }
            $out += ('#' * $level) + ' ' + $tagPrefix + $t
        }
        elseif ($checkbox) {
            $out += "$indent$checkbox $tagPrefix$text"
        }
        elseif ($listMarker) {
            $out += "$indent$listMarker $tagPrefix$text"
        }
        elseif ($styleName -eq 'cite' -or $styleName -eq 'blockquote') {
            foreach ($line in ($text -split "`n")) { $out += "$indent> $line" }
        }
        elseif ($styleName -eq 'code') {
            $out += "$indent``````"
            foreach ($line in ($text -split "`n")) { $out += "$indent$line" }
            $out += "$indent``````"
        }
        else {
            # A soft break inside a paragraph becomes a hard Markdown line break.
            # A tag prefix belongs on the first line only.
            $lines = $text -split "`n"
            for ($i = 0; $i -lt $lines.Count; $i++) {
                $suffix = ''
                if ($i -lt $lines.Count - 1) { $suffix = '  ' }
                $prefix = ''
                if ($i -eq 0) { $prefix = $tagPrefix }
                $out += "$indent$prefix$($lines[$i])$suffix"
            }
        }
    }
    elseif ($checkbox) {
        $out += "$indent$checkbox"
    }
    elseif ($sawText -and $blocks.Count -eq 0) {
        # An OE whose text is empty is a blank line the author left on purpose.
        # Markdown collapses blank lines, so make the gap explicit: a paragraph
        # holding a single non-breaking space. Renderers that escape raw HTML
        # (Orbit does) would show a literal '<br>', so a bare U+00A0 it is.
        $out += "$indent" + [char]0xA0
    }

    $out += $blocks
    return $out
}

function Convert-OeChildren {
    param($OeChildren, $Ctx, [int] $Depth)

    $out      = @()
    $prevList = $false

    foreach ($oe in (Get-ChildElements $OeChildren)) {
        if ($oe.LocalName -ne 'OE') { continue }

        $lines = @(Convert-Oe -Oe $oe -Ctx $Ctx -Depth $Depth)
        if ($lines.Count -eq 0) { continue }

        $isList = $lines[0] -match '^\s*(-|\d+\.)\s'

        # Blank line between blocks, but not between consecutive list items --
        # that would break the list into separate loose lists. Trim space/tab
        # only: a deliberate-gap line holds a U+00A0 and must count as content.
        if ($out.Count -gt 0 -and -not ($isList -and $prevList)) {
            if ($out[-1].Trim(' ', "`t").Length -gt 0) { $out += '' }
        }

        $out     += $lines
        $prevList = $isList
    }

    return $out
}

#endregion

#region Page export

function Format-MarkdownBody {
    <#
        Safety net over the emitted lines:
          * re-baselines each contiguous run of non-blank lines so its shallowest
            line sits at column 0 -- a run that starts at 4+ spaces with no parent
            list would otherwise be parsed as an indented code block
          * collapses runs of blank lines down to one
        Fenced code blocks are passed through untouched.
    #>
    param([string[]] $Lines)

    # Collapse runs of deliberate-gap lines (a lone U+00A0 from empty paragraphs):
    # pasted emails stack many empty rows, and one gap reads the same as six.
    # Full Trim() removes U+00A0; Trim(' ',tab) does not -- that difference is
    # exactly what identifies a gap line.
    $filtered   = New-Object System.Collections.ArrayList
    $gapPending = $false
    foreach ($line in $Lines) {
        $isGap = ($line.Trim(' ', "`t").Length -gt 0) -and ($line.Trim().Length -eq 0)
        if ($isGap) {
            if ($gapPending) { continue }
            $gapPending = $true
        }
        elseif ($line.Trim().Length -gt 0) { $gapPending = $false }
        [void]$filtered.Add($line)
    }
    $Lines = @($filtered)

    $out     = New-Object System.Collections.ArrayList
    $inFence = $false
    $run     = New-Object System.Collections.ArrayList

    $flushRun = {
        if ($run.Count -eq 0) { return }
        $min = [int]::MaxValue
        foreach ($l in $run) {
            $indent = $l.Length - $l.TrimStart(' ').Length
            if ($indent -lt $min) { $min = $indent }
        }
        if ($min -eq [int]::MaxValue) { $min = 0 }

        # A run whose FIRST line is 4+ spaces deep opens an indented code block, even
        # when a later line in the same run sits at column 0 (so re-baselining on the
        # run minimum alone is not enough). Shift the whole run left until the opening
        # line clears the 4-space threshold, clamping at column 0.
        $first = $run[0]
        $firstIndent = ($first.Length - $first.TrimStart(' ').Length) - $min
        $extra = 0
        if ($firstIndent -ge 4) { $extra = $firstIndent - 2 }

        foreach ($l in $run) {
            $indent = $l.Length - $l.TrimStart(' ').Length
            $target = [Math]::Max(0, $indent - $min - $extra)
            [void]$out.Add((' ' * $target) + $l.TrimStart(' '))
        }
        $run.Clear()
    }

    foreach ($line in $Lines) {
        if ($line -match '^\s*```') {
            & $flushRun
            $inFence = -not $inFence
            [void]$out.Add($line)
            continue
        }
        if ($inFence) { [void]$out.Add($line); continue }

        # Space/tab only: default Trim() also removes U+00A0, which would collapse
        # the deliberate-gap lines Convert-Oe emits for empty paragraphs.
        if ($line.Trim(' ', "`t").Length -eq 0) {
            & $flushRun
            if ($out.Count -gt 0 -and $out[$out.Count - 1].Trim(' ', "`t").Length -gt 0) {
                [void]$out.Add('')
            }
            continue
        }
        [void]$run.Add($line)
    }
    & $flushRun

    return ,@($out)
}

function Get-PriorLastModified {
    <#
        Resume state. Front matter is opt-in now, so the export log is the primary
        record of what revision each file was written from; the front-matter reader
        stays as a fallback for output produced by older versions of this script.
    #>
    param([hashtable] $PriorLog, [string] $PageId, [string] $Path)

    $row = $PriorLog[$PageId]
    if ($row -and $row.PSObject.Properties['LastModified']) {
        if (-not [string]::IsNullOrWhiteSpace($row.LastModified)) { return $row.LastModified }
    }
    return (Get-ExistingLastModified -Path $Path)
}

function Get-ExistingLastModified {
    param([string] $Path)
    if (-not (Test-Path -LiteralPath $Path)) { return $null }
    try {
        $head = Get-Content -LiteralPath $Path -TotalCount 20 -ErrorAction Stop
        foreach ($line in $head) {
            if ($line -match '^lastModified:\s*"?([^"]+)"?\s*$') { return $Matches[1].Trim() }
        }
    }
    catch { return $null }
    return $null
}

function Export-OneNotePage {
    param(
        $App,
        $PageNode,          # from GetHierarchy
        [string] $NotebookName,
        [string] $SectionPath,
        [string] $PageDir,
        [string] $FileName,
        [int]    $Order,
        [switch] $NoHydrateImages,
        [int]    $HydrateWaitMs = 1200,
        [int]    $HydrateMaxMs = 30000,
        [switch] $IncludeFrontMatter
    )

    $pageId       = Get-Attr $PageNode 'ID'
    $title        = Get-Attr $PageNode 'name' 'Untitled'
    $lastModified = Get-Attr $PageNode 'lastModifiedTime'
    $created      = Get-Attr $PageNode 'dateTime'
    $pageLevel    = Get-Attr $PageNode 'pageLevel' '1'

    $fetchPage = {
        [ref]$raw = ''
        $App.GetPageContent($pageId, $raw, $script:PI_BASIC, $script:XS_CURRENT)
        $d = [xml]$raw.Value
        $p = $d.SelectSingleNode("/*[local-name()='Page']")
        if ($null -eq $p) { throw 'Page element not found in returned XML' }
        return $p
    }

    $page = & $fetchPage

    # Notebooks hosted on SharePoint/OneDrive download page text eagerly but embedded
    # image blobs only when the page is actually viewed. Such an image comes back with
    # no 'format' attribute, and GetBinaryPageContent fails with 0x8004200F
    # (hrBinaryObjectDoesNotExist). NavigateTo() makes OneNote load the page, which
    # pulls the blobs down; we then re-read the XML and the images extract normally.
    # Blobs arrive progressively, so keep waiting only while the pending count is
    # actually falling. Two rounds without progress means the rest are not coming.
    $countPending = {
        param($P)
        $n = 0
        foreach ($img in $P.SelectNodes("//*[local-name()='Image']")) {
            if ([string]::IsNullOrWhiteSpace((Get-Attr $img 'format'))) { $n++ }
        }
        return $n
    }

    $hydrations = 0
    if (-not $NoHydrateImages) {
        $lastPending = [int]::MaxValue
        $stalls      = 0
        $waited      = 0

        while ($waited -lt $HydrateMaxMs) {
            $pending = & $countPending $page
            if ($pending -eq 0) { break }

            if ($pending -ge $lastPending) { $stalls++ } else { $stalls = 0 }
            if ($stalls -ge 2) { break }
            $lastPending = $pending

            try { $App.NavigateTo($pageId, '', $false) }
            catch { Write-Verbose "NavigateTo failed for '$title': $($_.Exception.Message)"; break }

            Start-Sleep -Milliseconds $HydrateWaitMs
            $waited += $HydrateWaitMs
            $page = & $fetchPage
            $hydrations++
        }
    }

    # Style and tag definition lookups, keyed by index.
    $quickStyles = @{}
    foreach ($q in $page.SelectNodes("*[local-name()='QuickStyleDef']")) {
        $quickStyles[(Get-Attr $q 'index')] = (Get-Attr $q 'name')
    }
    $tagDefs = @{}
    foreach ($t in $page.SelectNodes("*[local-name()='TagDef']")) {
        $tagDefs[(Get-Attr $t 'index')] = @{
            Name   = (Get-Attr $t 'name')
            Symbol = (Get-Attr $t 'symbol')
            Type   = (Get-Attr $t 'type')
        }
    }

    $ctx = @{
        App         = $App
        PageId      = $pageId
        PageTitle   = $title
        PageSlug    = (Get-Slug $title)
        PageDir     = $PageDir
        QuickStyles = $quickStyles
        TagDefs     = $tagDefs
        PageTags    = @{}
        Warnings    = New-Object System.Collections.ArrayList
        ImageIndex  = 0
        ImagesSaved = 0
        FilesSaved  = 0
        CreatedUtc  = (ConvertTo-UtcOrNull $created)
        ModifiedUtc = (ConvertTo-UtcOrNull $lastModified)
    }

    # Gather top-level content containers and order them by on-page position
    # (top to bottom, then left to right), since OneNote stores them unordered.
    $containers = @()
    foreach ($child in (Get-ChildElements $page)) {
        if ($child.LocalName -notin @('Outline', 'Image', 'InkDrawing', 'InsertedFile', 'MediaFile')) { continue }
        $x = 0.0; $y = 0.0
        foreach ($c in (Get-ChildElements $child)) {
            if ($c.LocalName -eq 'Position') {
                [double]::TryParse((Get-Attr $c 'x' '0'), [ref]$x) | Out-Null
                [double]::TryParse((Get-Attr $c 'y' '0'), [ref]$y) | Out-Null
                break
            }
        }
        $containers += [pscustomobject]@{ Node = $child; X = $x; Y = $y }
    }
    $containers = @($containers | Sort-Object Y, X)

    $blocks = @()
    foreach ($container in $containers) {
        $node  = $container.Node
        $lines = @()

        if ($node.LocalName -eq 'Outline') {
            foreach ($c in (Get-ChildElements $node)) {
                if ($c.LocalName -eq 'OEChildren') {
                    $lines += Convert-OeChildren -OeChildren $c -Ctx $ctx -Depth 0
                }
            }
        }
        elseif ($node.LocalName -eq 'Image') {
            $lines += (Save-PageImage -Image $node -Ctx $ctx)
        }
        elseif ($node.LocalName -eq 'InkDrawing') {
            $ctx.Warnings.Add('ink-not-exported') | Out-Null
            $lines += '> [!WARNING] Handwritten ink on this page was not exported.'
        }
        elseif ($node.LocalName -in @('InsertedFile', 'MediaFile')) {
            $f = Copy-EmbeddedFile -Node $node -Ctx $ctx
            if ($f.Copied) {
                $lines += $f.Link
            } else {
                $ctx.Warnings.Add("attachment-missing:$($f.Name)") | Out-Null
                $lines += "``[attachment: $($f.Name)]``"
            }
        }

        if ($lines.Count -gt 0) { $blocks += ,$lines }
    }

    $body = New-Object System.Collections.ArrayList
    for ($i = 0; $i -lt $blocks.Count; $i++) {
        if ($i -gt 0) {
            [void]$body.Add('')
            [void]$body.Add('---')
            [void]$body.Add('')
        }
        foreach ($line in $blocks[$i]) { [void]$body.Add($line) }
    }

    # Front matter
    $tagList = ''
    if ($ctx.PageTags.Count -gt 0) {
        $tagList = '[' + (($ctx.PageTags.Keys | Sort-Object | ForEach-Object { '"' + $_ + '"' }) -join ', ') + ']'
    }

    $fm = New-Object System.Collections.ArrayList
    if ($IncludeFrontMatter) {
        [void]$fm.Add('---')
        [void]$fm.Add('title: "' + ($title -replace '"', '\"') + '"')
        [void]$fm.Add('notebook: "' + ($NotebookName -replace '"', '\"') + '"')
        [void]$fm.Add('section: "' + ($SectionPath -replace '"', '\"') + '"')
        [void]$fm.Add('onenotePageId: "' + $pageId + '"')
        [void]$fm.Add('created: "' + $created + '"')
        [void]$fm.Add('lastModified: "' + $lastModified + '"')
        [void]$fm.Add('pageLevel: ' + $pageLevel)
        [void]$fm.Add('order: ' + $Order)
        if ($tagList) { [void]$fm.Add('tags: ' + $tagList) }
        [void]$fm.Add('---')
        [void]$fm.Add('')
    }
    [void]$fm.Add('# ' + (ConvertTo-EscapedText $title))
    [void]$fm.Add('')

    $cleanBody = Format-MarkdownBody -Lines @($body)
    $content = ((@($fm) + @($cleanBody)) -join "`r`n").TrimEnd() + "`r`n"

    if (-not (Test-Path -LiteralPath $PageDir)) {
        New-Item -ItemType Directory -Path $PageDir -Force | Out-Null
    }
    $outFile = Join-Path $PageDir $FileName
    [System.IO.File]::WriteAllText($outFile, $content, (New-Object System.Text.UTF8Encoding $false))

    # Mirror the page's own timestamps onto the file, so sorting by date in
    # Explorer (or anything reading file metadata) matches OneNote. The hierarchy
    # reports both as ISO 8601 UTC ('2026-07-23T00:33:32.000Z').
    try {
        $inv    = [System.Globalization.CultureInfo]::InvariantCulture
        $styles = [System.Globalization.DateTimeStyles]::AdjustToUniversal
        if (-not [string]::IsNullOrWhiteSpace($created)) {
            [System.IO.File]::SetCreationTimeUtc($outFile, [DateTime]::Parse($created, $inv, $styles))
        }
        if (-not [string]::IsNullOrWhiteSpace($lastModified)) {
            [System.IO.File]::SetLastWriteTimeUtc($outFile, [DateTime]::Parse($lastModified, $inv, $styles))
        }
    }
    catch {
        $ctx.Warnings.Add('timestamp-not-set') | Out-Null
        Write-Verbose "Could not set file timestamps for '$title': $($_.Exception.Message)"
    }

    return [pscustomobject]@{
        Path        = $outFile
        Images      = $ctx.ImagesSaved
        Files       = $ctx.FilesSaved
        Warnings    = (($ctx.Warnings | Select-Object -Unique) -join '; ')
        Hydrations  = $hydrations
        HasOneNoteLink = ($content -match 'onenote:')
    }
}

#endregion

#region Hierarchy walk

function Get-SectionsRecursive {
    <#
        Yields section nodes with their section-group path, skipping the recycle bin.
    #>
    param($Node, [string] $PathSoFar)

    $result = @()
    foreach ($child in (Get-ChildElements $Node)) {
        if ($child.LocalName -eq 'Section') {
            if ((Get-Attr $child 'isInRecycleBin' 'false') -eq 'true') { continue }
            $result += [pscustomobject]@{ Node = $child; GroupPath = $PathSoFar }
        }
        elseif ($child.LocalName -eq 'SectionGroup') {
            if ((Get-Attr $child 'isRecycleBin' 'false') -eq 'true') { continue }
            $name = Get-Attr $child 'name'
            $next = if ($PathSoFar) { "$PathSoFar/$name" } else { $name }
            $result += Get-SectionsRecursive -Node $child -PathSoFar $next
        }
    }
    return $result
}

#endregion

#region Link resolution pass

function Get-RelativePath {
    # .NET Framework has no Path.GetRelativePath, so use Uri math.
    param([string] $FromDir, [string] $ToFile)
    $fromUri = New-Object System.Uri (($FromDir.TrimEnd('\')) + '\')
    $toUri   = New-Object System.Uri $ToFile
    $rel     = [System.Uri]::UnescapeDataString($fromUri.MakeRelativeUri($toUri).ToString())
    return ($rel -replace '/', '\')
}

function Resolve-OneNoteLinks {
    <#
        Rewrites onenote: hyperlinks between exported pages into relative .md links.

        The page-id in a onenote: hyperlink is NOT the leading GUID of the hierarchy
        Page@ID -- that leading GUID is the *section* identifier, shared by every page
        in the section. The only reliable source for a page's hyperlink identity is
        GetHyperlinkToObject(). That costs a COM round trip per page (~57ms), so it is
        done lazily: only when links actually exist, and only until every referenced
        id has been located.
    #>
    param($App, $AllPages, [string[]] $FilesToFix)

    # 1. Which page-ids are actually referenced?
    $needed   = @{}
    $fileText = @{}
    foreach ($file in $FilesToFix) {
        if (-not (Test-Path -LiteralPath $file)) { continue }
        $text = [System.IO.File]::ReadAllText($file)
        $fileText[$file] = $text
        foreach ($m in [regex]::Matches($text, '\(<?(onenote:[^)>]*)>?\)')) {
            if ($m.Groups[1].Value -match 'page-id=(\{[0-9A-Fa-f\-]+\})') {
                $needed[$Matches[1].ToUpperInvariant()] = $true
            }
        }
    }

    if ($needed.Count -eq 0) {
        return [pscustomobject]@{ Resolved = 0; Unresolved = 0; Scanned = 0; Referenced = 0 }
    }

    # 2. Walk pages asking OneNote for each one's canonical hyperlink, stopping as
    #    soon as every referenced id has been matched.
    $map       = @{}
    $remaining = $needed.Count
    $scanned   = 0
    Write-Host "  looking up $remaining referenced page id(s)..." -ForegroundColor DarkGray

    foreach ($item in $AllPages) {
        if ($remaining -le 0) { break }
        $scanned++
        [ref]$link = ''
        try { $App.GetHyperlinkToObject((Get-Attr $item.Node 'ID'), '', $link) }
        catch { continue }
        if ($link.Value -match 'page-id=(\{[0-9A-Fa-f\-]+\})') {
            $key = $Matches[1].ToUpperInvariant()
            if ($needed.ContainsKey($key) -and -not $map.ContainsKey($key)) {
                $map[$key] = Join-Path $item.Dir $item.FileName
                $remaining--
            }
        }
    }

    # 3. Rewrite.
    $resolved = 0
    $missed   = 0

    foreach ($file in $fileText.Keys) {
        $text = $fileText[$file]
        $dir  = Split-Path -Parent $file

        $script:linkFixCount  = 0
        $script:linkMissCount = 0
        $new = [regex]::Replace($text, '\(<?(onenote:[^)>]*)>?\)', {
            param($m)
            $url = $m.Groups[1].Value
            if ($url -match 'page-id=(\{[0-9A-Fa-f\-]+\})') {
                $key = $Matches[1].ToUpperInvariant()
                if ($map.ContainsKey($key)) {
                    $rel = (Get-RelativePath -FromDir $dir -ToFile $map[$key]) -replace '\\', '/'
                    $script:linkFixCount++
                    return '(' + ($rel -replace ' ', '%20') + ')'
                }
            }
            $script:linkMissCount++
            return $m.Value
        })

        if ($new -ne $text) {
            # Rewriting must not disturb the OneNote timestamps stamped at export.
            $stamp = [System.IO.File]::GetLastWriteTimeUtc($file)
            [System.IO.File]::WriteAllText($file, $new, (New-Object System.Text.UTF8Encoding $false))
            [System.IO.File]::SetLastWriteTimeUtc($file, $stamp)
        }
        $resolved += $script:linkFixCount
        $missed   += $script:linkMissCount
    }

    return [pscustomobject]@{
        Resolved = $resolved; Unresolved = $missed
        Scanned  = $scanned;  Referenced = $needed.Count
    }
}

#endregion

#region Main

# When no -Notebook was passed we assume a person double-clicked / right-clicked the
# file, so the window must stay open long enough for them to read the result.
$script:InteractiveRun = -not $PSBoundParameters.ContainsKey('Notebook')

function Wait-ForUser {
    if (-not $script:InteractiveRun) { return }
    Write-Host ''
    try { Read-Host 'Press Enter to close this window' | Out-Null } catch { }
}

# Show a readable message instead of a red wall of PowerShell internals.
trap {
    Write-Host ''
    Write-Host '-----------------------------------------------------------' -ForegroundColor Red
    Write-Host ' The export stopped before it finished.' -ForegroundColor Red
    Write-Host '-----------------------------------------------------------' -ForegroundColor Red
    Write-Host ''
    Write-Host $_.Exception.Message -ForegroundColor Yellow
    Write-Host ''
    Write-Host 'If that does not tell you what to do, send a screenshot of this'
    Write-Host 'whole window to whoever gave you this tool.'
    Wait-ForUser
    exit 1
}

Write-Host ''
Write-Host 'OneNote to Markdown export' -ForegroundColor Cyan
Write-Host '--------------------------' -ForegroundColor Cyan

Assert-Environment

switch ($UnderlineAs) {
    'plus'   { $script:UnderlineMarkers = @('++', '++') }
    'bold'   { $script:UnderlineMarkers = @('**', '**') }
    'italic' { $script:UnderlineMarkers = @('*', '*') }
    'html'   { $script:UnderlineMarkers = @('<u>', '</u>') }
    'none'   { $script:UnderlineMarkers = $null }
}

switch ($HighlightAs) {
    'html'   { $script:HighlightMarkers = @('<mark>', '</mark>') }
    'equals' { $script:HighlightMarkers = @('==', '==') }
    'none'   { $script:HighlightMarkers = $null }
}

if ([string]::IsNullOrWhiteSpace($OutputRoot)) {
    $OutputRoot = Join-Path $PSScriptRoot 'out'
}

# Must be absolute: paths recorded in the log and the stale-file scan are compared
# against Get-ChildItem's FullName, so a relative root would never match.
if (-not (Test-Path -LiteralPath $OutputRoot)) {
    New-Item -ItemType Directory -Path $OutputRoot -Force | Out-Null
}
$OutputRoot = (Resolve-Path -LiteralPath $OutputRoot).Path

# Carry the previous run's per-page outcome forward. Skipped pages re-emit their
# prior warnings so the log stays complete across resume runs, and -RetryFailed
# has something to select on.
$priorLog = @{}
$priorLogPath = Join-Path $OutputRoot '_export-log.csv'
if (Test-Path -LiteralPath $priorLogPath) {
    try {
        foreach ($row in (Import-Csv -LiteralPath $priorLogPath)) {
            if ($row.PageId) { $priorLog[$row.PageId] = $row }
        }
    }
    catch { Write-Verbose "Could not read prior log: $($_.Exception.Message)" }
}

Write-Host "Attaching to OneNote..." -ForegroundColor Cyan
$app = Get-OneNoteApp

Write-Host "Reading notebook hierarchy..." -ForegroundColor Cyan
[ref]$hierarchyXml = ''
$app.GetHierarchy('', $script:HS_PAGES, $hierarchyXml)
$hierarchy = [xml]$hierarchyXml.Value

$allNotebooks = @($hierarchy.SelectNodes("/*/*[local-name()='Notebook']"))
if ($allNotebooks.Count -eq 0) {
    throw "No notebooks are open in OneNote. Open the notebook you want to export, let it finish syncing, then run this again."
}

# One notebook per run. Named on the command line, or chosen from a list.
$chosen = $null

if ($Notebook) {
    $chosen = $allNotebooks | Where-Object { (Get-Attr $_ 'name') -eq $Notebook } | Select-Object -First 1
    if (-not $chosen) {
        $chosen = $allNotebooks | Where-Object { (Get-Attr $_ 'name') -like $Notebook } | Select-Object -First 1
    }
    if (-not $chosen) {
        $names = ($allNotebooks | ForEach-Object { '  - ' + (Get-Attr $_ 'name') }) -join "`r`n"
        throw "Could not find a notebook called '$Notebook'. Notebooks currently open are:`r`n$names"
    }
}
else {
    # Count pages per notebook so the list is informative, skipping the recycle bin.
    $menu = @()
    foreach ($nb in $allNotebooks) {
        $pageCount = 0
        foreach ($entry in (Get-SectionsRecursive -Node $nb -PathSoFar '')) {
            $kids = Get-ChildElements $entry.Node
            $pageCount += @($kids | Where-Object { $_.LocalName -eq 'Page' }).Count
        }
        $menu += [pscustomobject]@{ Node = $nb; Name = (Get-Attr $nb 'name' 'Notebook'); Pages = $pageCount }
    }
    $menu = @($menu | Sort-Object Name)

    Write-Host ''
    Write-Host 'Which notebook do you want to export?' -ForegroundColor Green
    Write-Host ''
    for ($i = 0; $i -lt $menu.Count; $i++) {
        Write-Host ('  {0,2}. {1,-40} {2,6} pages' -f ($i + 1), $menu[$i].Name, $menu[$i].Pages)
    }
    Write-Host ''

    while ($null -eq $chosen) {
        $answer = Read-Host "Type a number from 1 to $($menu.Count) and press Enter"
        if ($answer -match '^\s*(\d+)\s*$') {
            $pick = [int]$Matches[1]
            if ($pick -ge 1 -and $pick -le $menu.Count) { $chosen = $menu[$pick - 1].Node }
        }
        if ($null -eq $chosen) { Write-Host "  Sorry, '$answer' is not one of the numbers above." -ForegroundColor Yellow }
    }
}

$notebooks = @($chosen)
Write-Host ''
Write-Host "Exporting: $(Get-Attr $chosen 'name')" -ForegroundColor Green

# ---- Build the work list -------------------------------------------------

$work        = New-Object System.Collections.ArrayList
$lockedList  = New-Object System.Collections.ArrayList
$pageIdToPath = @{}

foreach ($nb in $notebooks) {
    $nbName   = Get-Attr $nb 'name' 'Notebook'
    $nbFolder = Get-SafeName -Name $nbName -Used $null

    foreach ($entry in (Get-SectionsRecursive -Node $nb -PathSoFar '')) {
        $section = $entry.Node
        $secName = Get-Attr $section 'name' 'Section'

        if ((Get-Attr $section 'locked' 'false') -eq 'true') {
            [void]$lockedList.Add("$nbName / $($entry.GroupPath)/$secName".Replace('//', '/'))
            continue
        }

        $sectionPath = if ($entry.GroupPath) { "$($entry.GroupPath)/$secName" } else { $secName }

        # Build the on-disk directory, sanitising each path segment.
        $dir = Join-Path $OutputRoot $nbFolder
        foreach ($seg in ($sectionPath -split '/')) {
            $dir = Join-Path $dir (Get-SafeName -Name $seg -Used $null)
        }

        # OneNote page groups: a page at pageLevel 1 followed by pageLevel 2/3 pages is
        # a parent with subpages. Turn each parent into a folder, so twelve candidates
        # each holding a "Phone Screen" page become
        # <Candidate>/Phone Screen.md rather than Phone Screen-2 .. Phone Screen-12.
        # Assign before filtering. Get-ChildElements returns ,$array to stop PowerShell
        # unrolling it, which means piping it straight into Where-Object hands over the
        # whole array as a single object instead of one element at a time.
        $sectionChildren = Get-ChildElements $section
        $pages = @($sectionChildren | Where-Object { $_.LocalName -eq 'Page' })

        # A page is a parent when the next page sits at a deeper level.
        $isParent = New-Object bool[] $pages.Count
        for ($i = 0; $i -lt $pages.Count; $i++) {
            if ($i + 1 -lt $pages.Count) {
                # Index into locals first: PowerShell mis-parses $pages[$i + 1] when it
                # appears directly as a command argument.
                $curPage  = $pages[$i]
                $nextPage = $pages[$i + 1]
                $isParent[$i] = ([int](Get-Attr $nextPage 'pageLevel' '1') -gt
                                 [int](Get-Attr $curPage  'pageLevel' '1'))
            }
        }

        # Names must be unique per target directory, so track usage by directory.
        $usedByDir = @{}
        $getUsed = {
            param([string] $D)
            if (-not $usedByDir.ContainsKey($D)) { $usedByDir[$D] = @{} }
            return $usedByDir[$D]
        }

        $segments = New-Object System.Collections.Generic.List[string]
        $order = 0

        for ($i = 0; $i -lt $pages.Count; $i++) {
            $pg = $pages[$i]
            $order++
            $title = Get-Attr $pg 'name' 'Untitled'
            $level = [int](Get-Attr $pg 'pageLevel' '1')
            if ($level -lt 1) { $level = 1 }

            # Leave any folders deeper than this page's parent level.
            if (-not $FlattenPageGroups) {
                while ($segments.Count -gt ($level - 1)) {
                    $segments.RemoveAt($segments.Count - 1)
                }
            }

            $parentDir = $dir
            foreach ($seg in $segments) { $parentDir = Join-Path $parentDir $seg }

            if ($isParent[$i] -and -not $FlattenPageGroups) {
                # Folder for the group, plus a same-named note holding this page's own
                # content, which reads as a folder note in Obsidian/Orbit.
                $folder  = Get-SafeName -Name $title -Used (& $getUsed $parentDir)
                $pageDir = Join-Path $parentDir $folder
                $base    = Get-SafeName -Name $folder -Used (& $getUsed $pageDir)
                $segments.Add($folder)
            }
            else {
                $pageDir = $parentDir
                $base    = Get-SafeName -Name $title -Used (& $getUsed $pageDir)
            }

            $fileName = "$base.md"

            $item = [pscustomobject]@{
                Node         = $pg
                NotebookName = $nbName
                SectionPath  = $sectionPath
                Dir          = $pageDir
                FileName     = $fileName
                Order        = $order
            }
            [void]$work.Add($item)

            # Full hierarchy ID -> path. Note the leading GUID alone is the SECTION id,
            # so it must not be used as a page key.
            $pageIdToPath[(Get-Attr $pg 'ID')] = (Join-Path $pageDir $fileName)
        }
    }
}

# ---- Export --------------------------------------------------------------

if ($lockedList.Count -gt 0) {
    Write-Host ''
    Write-Host "Skipping $($lockedList.Count) password-protected section(s):" -ForegroundColor Yellow
    $lockedList | Select-Object -Unique | ForEach-Object { Write-Host "  $_" -ForegroundColor Yellow }
    Write-Host '  Unlock them in OneNote first if you need them.' -ForegroundColor Yellow
}

# Link resolution needs every page in scope, not just the subset this run exports,
# so keep an unfiltered copy before -RetryFailed narrows the work list.
$allPages = @($work)

if ($RetryFailed) {
    if ($priorLog.Count -eq 0) {
        throw "-RetryFailed needs a previous run's _export-log.csv in $OutputRoot"
    }
    $work = New-Object System.Collections.ArrayList (,@($work | Where-Object {
        $row = $priorLog[(Get-Attr $_.Node 'ID')]
        $row -and ($row.Status -eq 'failed' -or -not [string]::IsNullOrWhiteSpace($row.Warnings))
    }))
    Write-Host "Retrying $($work.Count) page(s) that previously failed or warned." -ForegroundColor Yellow
    if ($work.Count -eq 0) { return }
    $Force = $true
}

$total = $work.Count

Write-Host ''
Write-Host "$total page(s) to export. Saving to:" -ForegroundColor Green
Write-Host "  $OutputRoot"
Write-Host 'Please leave OneNote alone until this finishes.' -ForegroundColor Yellow
Write-Host ''
if (-not (Test-Path -LiteralPath $OutputRoot)) {
    New-Item -ItemType Directory -Path $OutputRoot -Force | Out-Null
}

$log            = New-Object System.Collections.ArrayList
$filesWithLinks = New-Object System.Collections.ArrayList
$done = 0; $skipped = 0; $failed = 0; $images = 0; $hydrated = 0
$sw = [System.Diagnostics.Stopwatch]::StartNew()

foreach ($item in $work) {
    $done++

    $title   = Get-Attr $item.Node 'name' 'Untitled'
    $outFile = Join-Path $item.Dir $item.FileName

    $pct = [int](100 * $done / [Math]::Max($total, 1))
    $eta = ''
    if ($done -gt 3) {
        $perPage = $sw.Elapsed.TotalSeconds / $done
        $eta = ' | ETA {0:hh\:mm\:ss}' -f [TimeSpan]::FromSeconds($perPage * ($total - $done))
    }
    Write-Progress -Activity "Exporting OneNote" `
                   -Status "$done/$total  $($item.NotebookName) / $($item.SectionPath)$eta" `
                   -CurrentOperation $title -PercentComplete ([Math]::Min($pct, 100))

    # Resume: skip when on-disk content already matches this revision.
    if (-not $Force) {
        $existing = Get-PriorLastModified -PriorLog $priorLog `
                        -PageId (Get-Attr $item.Node 'ID') -Path $outFile
        if ($existing -and (Test-Path -LiteralPath $outFile) -and
            $existing -eq (Get-Attr $item.Node 'lastModifiedTime')) {
            $skipped++

            # A skipped page still gets its links re-examined, so a resume run repairs
            # any onenote: links an earlier run left unresolved.
            try {
                if ((Get-Content -LiteralPath $outFile -Raw) -match 'onenote:') {
                    [void]$filesWithLinks.Add($outFile)
                }
            }
            catch { }

            $pageIdKey = Get-Attr $item.Node 'ID'
            $prior = $priorLog[$pageIdKey]
            [void]$log.Add([pscustomobject]@{
                Notebook = $item.NotebookName; Section = $item.SectionPath
                Title    = $title;             Path    = $outFile
                Images   = if ($prior) { $prior.Images } else { 0 }
                Files    = if ($prior) { $prior.Files } else { 0 }
                Hydrations = 0
                Status   = 'skipped'
                Warnings = if ($prior) { $prior.Warnings } else { '' }
                PageId   = $pageIdKey; ElapsedMs = 0
                LastModified = (Get-Attr $item.Node 'lastModifiedTime')
            })
            continue
        }
    }

    $pageSw = [System.Diagnostics.Stopwatch]::StartNew()
    try {
        $result = Export-OneNotePage -App $app -PageNode $item.Node `
                    -NotebookName $item.NotebookName -SectionPath $item.SectionPath `
                    -PageDir $item.Dir -FileName $item.FileName -Order $item.Order `
                    -NoHydrateImages:$NoHydrateImages -HydrateWaitMs $HydrateWaitMs `
                    -HydrateMaxMs $HydrateMaxMs -IncludeFrontMatter:$IncludeFrontMatter

        $images += $result.Images
        $hydrated += $result.Hydrations
        if ($result.HasOneNoteLink) { [void]$filesWithLinks.Add($result.Path) }

        [void]$log.Add([pscustomobject]@{
            Notebook = $item.NotebookName; Section = $item.SectionPath
            Title    = $title;             Path    = $result.Path
            Images   = $result.Images;     Files   = $result.Files
            Hydrations = $result.Hydrations
            Status   = 'ok';               Warnings = $result.Warnings
            PageId   = (Get-Attr $item.Node 'ID'); ElapsedMs = $pageSw.ElapsedMilliseconds
            LastModified = (Get-Attr $item.Node 'lastModifiedTime')
        })
    }
    catch {
        $failed++
        Write-Warning "FAILED: $($item.NotebookName) / $($item.SectionPath) / $title -- $($_.Exception.Message)"
        [void]$log.Add([pscustomobject]@{
            Notebook = $item.NotebookName; Section = $item.SectionPath
            Title    = $title;             Path    = $outFile
            Images   = 0;                  Files   = 0
            Hydrations = 0
            Status   = 'failed';           Warnings = $_.Exception.Message
            PageId   = (Get-Attr $item.Node 'ID'); ElapsedMs = $pageSw.ElapsedMilliseconds
            LastModified = ''
        })
    }

    # Keep RCW pressure down over a long run.
    if ($done % 250 -eq 0) { [GC]::Collect(); [GC]::WaitForPendingFinalizers() }
}

Write-Progress -Activity "Exporting OneNote" -Completed
$sw.Stop()

# ---- Second pass: internal onenote: links --------------------------------

$linkStats = [pscustomobject]@{ Resolved = 0; Unresolved = 0; Scanned = 0; Referenced = 0 }
if ($filesWithLinks.Count -gt 0) {
    Write-Host "Resolving internal OneNote links in $($filesWithLinks.Count) file(s)..." -ForegroundColor Cyan
    $linkStats = Resolve-OneNoteLinks -App $app -AllPages $allPages -FilesToFix $filesWithLinks
}

# ---- Timestamps ----------------------------------------------------------

# Without this every file and folder shows the date the export ran. Done as a final
# pass, after the link rewrite above, because editing a file bumps its modified time
# again -- and after all writes, because creating a file bumps its folder's too.
Write-Host 'Applying OneNote dates to files and folders...' -ForegroundColor Cyan

$dirTimes = @{}

foreach ($item in $allPages) {
    $createdUtc  = ConvertTo-UtcOrNull (Get-Attr $item.Node 'dateTime')
    $modifiedUtc = ConvertTo-UtcOrNull (Get-Attr $item.Node 'lastModifiedTime')

    # Runs for skipped pages too, so re-running repairs an earlier export.
    Set-ItemTimestamps -Path (Join-Path $item.Dir $item.FileName) `
                       -CreatedUtc $createdUtc -ModifiedUtc $modifiedUtc

    # A folder takes the earliest creation and latest modification of everything
    # beneath it, which is the closest honest equivalent -- OneNote records no
    # creation date for sections or section groups.
    # Stops at the notebook folder. The output root can hold several notebooks, so
    # stamping it with one notebook's dates would be misleading.
    $dir = $item.Dir
    while ($dir -and $dir.Length -gt $OutputRoot.Length) {
        if (-not $dirTimes.ContainsKey($dir)) {
            $dirTimes[$dir] = @{ Created = $createdUtc; Modified = $modifiedUtc }
        }
        else {
            $slot = $dirTimes[$dir]
            if ($createdUtc  -and (-not $slot.Created  -or $createdUtc  -lt $slot.Created))  { $slot.Created  = $createdUtc }
            if ($modifiedUtc -and (-not $slot.Modified -or $modifiedUtc -gt $slot.Modified)) { $slot.Modified = $modifiedUtc }
        }
        $parent = Split-Path -Parent $dir
        if ($parent -eq $dir) { break }
        $dir = $parent
    }
}

# Deepest first, so stamping a child can never disturb a parent we already set.
foreach ($dir in ($dirTimes.Keys | Sort-Object -Property Length -Descending)) {
    Set-ItemTimestamps -Path $dir -CreatedUtc $dirTimes[$dir].Created `
                       -ModifiedUtc $dirTimes[$dir].Modified
}

# 'media' folders sit beside the pages rather than under them, so give each one the
# dates of the folder it belongs to.
foreach ($dir in ($dirTimes.Keys | Sort-Object -Property Length -Descending)) {
    $mediaDir = Join-Path $dir 'media'
    if (Test-Path -LiteralPath $mediaDir) {
        Set-ItemTimestamps -Path $mediaDir -CreatedUtc $dirTimes[$dir].Created `
                           -ModifiedUtc $dirTimes[$dir].Modified
    }
}

# ---- Stale output detection ----------------------------------------------

# Renaming or deleting a page in OneNote leaves the previously exported file behind
# under its old name. Report those rather than deleting anything -- only meaningful
# after a complete pass over the notebooks in scope.
$orphans = New-Object System.Collections.ArrayList
if (-not $RetryFailed) {
    $expected = @{}
    $roots    = @{}
    foreach ($item in $allPages) {
        $expected[(Join-Path $item.Dir $item.FileName)] = $true
        $roots[(Join-Path $OutputRoot (Get-SafeName -Name $item.NotebookName -Used $null))] = $true
    }
    foreach ($root in $roots.Keys) {
        if (-not (Test-Path -LiteralPath $root)) { continue }
        foreach ($f in (Get-ChildItem -LiteralPath $root -Recurse -Filter *.md -File)) {
            if (-not $expected.ContainsKey($f.FullName)) { [void]$orphans.Add($f.FullName) }
        }
    }
    if ($orphans.Count -gt 0) {
        $orphans | Set-Content -LiteralPath (Join-Path $OutputRoot '_orphaned-files.txt') -Encoding UTF8
    }
}

# ---- Reports -------------------------------------------------------------

# Snapshot this run's outcome before merging history in.
$exported = @($log | Where-Object { $_.Status -eq 'ok' }).Count
$warned   = @($log | Where-Object { $_.Warnings }).Count

# A run covering one notebook must not erase log rows for other notebooks exported
# earlier, so carry unseen prior rows forward.
$seen = @{}
foreach ($r in $log) { if ($r.PageId) { $seen[$r.PageId] = $true } }
foreach ($k in $priorLog.Keys) {
    if (-not $seen.ContainsKey($k)) { [void]$log.Add($priorLog[$k]) }
}

$logPath = Join-Path $OutputRoot '_export-log.csv'
$log | Sort-Object Notebook, Section, Title |
    Export-Csv -LiteralPath $logPath -NoTypeInformation -Encoding UTF8

$mapPath = Join-Path $OutputRoot '_link-map.json'
$pageIdToPath | ConvertTo-Json -Depth 3 | Set-Content -LiteralPath $mapPath -Encoding UTF8

if ($lockedList.Count -gt 0) {
    $lockedPath = Join-Path $OutputRoot '_locked-sections.txt'
    $lockedList | Select-Object -Unique | Set-Content -LiteralPath $lockedPath -Encoding UTF8
}

$imagesMissed = 0
foreach ($r in $log) {
    if ($r.Warnings) {
        $imagesMissed += ([regex]::Matches([string]$r.Warnings, 'image-failed:')).Count
    }
}

Write-Host ''
Write-Host '-----------------------------------------------------------' -ForegroundColor Green
Write-Host ' Finished' -ForegroundColor Green
Write-Host '-----------------------------------------------------------' -ForegroundColor Green
Write-Host ''
Write-Host ('  Pages exported      {0}' -f $exported)
if ($skipped -gt 0) { Write-Host ('  Already up to date  {0}' -f $skipped) }
Write-Host ('  Pictures saved      {0}' -f $images)
Write-Host ('  Time taken          {0:hh\:mm\:ss}' -f $sw.Elapsed)
Write-Host ''
Write-Host '  Your files are here:' -ForegroundColor Cyan
Write-Host "  $OutputRoot"
Write-Host ''

if ($failed -gt 0) {
    Write-Host "  $failed page(s) could not be exported. See _export-log.csv in the" -ForegroundColor Red
    Write-Host '  folder above (look at the Warnings column).' -ForegroundColor Red
    Write-Host ''
}
if ($imagesMissed -gt 0) {
    Write-Host "  $imagesMissed picture(s) could not be saved, because OneNote has not" -ForegroundColor Yellow
    Write-Host '  downloaded them to this computer yet. To get them:' -ForegroundColor Yellow
    Write-Host '    1. In OneNote, right-click the notebook name' -ForegroundColor Yellow
    Write-Host '    2. Choose "Notebook Sync Status"' -ForegroundColor Yellow
    Write-Host '    3. Tick "Download all files and images", wait for it to finish' -ForegroundColor Yellow
    Write-Host '    4. Run this tool again' -ForegroundColor Yellow
    Write-Host ''
}
if ($orphans.Count -gt 0) {
    Write-Host "  $($orphans.Count) leftover file(s) no longer match a OneNote page (renamed or" -ForegroundColor Yellow
    Write-Host '  deleted since the last export). They are listed in _orphaned-files.txt.' -ForegroundColor Yellow
    Write-Host '  Nothing was deleted for you.' -ForegroundColor Yellow
    Write-Host ''
}

Wait-ForUser

#endregion