HtmlFragments.psm1
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 |
[System.IO.DirectoryInfo]$SCRIPT:moduleDir = Split-Path -Parent $MyInvocation.MyCommand.Path [string]$SCRIPT:svgbob = Join-Path $SCRIPT:moduleDir 'svgbob_cli.exe' # Send utf8 without BOM throught the pipe to external programs $OutputEncoding = [Text.UTF8Encoding]::new($false) # Match hyperlinks to Markdown files $SCRIPT:mdhrefRE = New-Object Regex '(?<=^<a[^>]*href=")([^"]+)\.(md|markdown)(?=["#])' <# .SYNOPSIS Convert fenced svgbob code blocks to svg images. .DESCRIPTION Scans the input data (lines of Markdown text) for svgbob fenced code blocks and converts them to a Markdown style image link to a svg file containing the rendered diagram. Svgbob code blocks define human readable diagrams and are labeled as `bob`. For example: ``` Markdown ~~~ bob +------+ .-. +---+ o----| elem |--( ; )--| n |----o +------+ '-' +---+ ~~~ ``` The generated svg file is put right next to the HTML file currently being assembled and named after that HTML file with an unique index appended. .PARAMETER SiteDirectory Location of the static HTML site. The Svg file will be generated relative to this path. .PARAMETER Options Svg conversion options. An object or hashtable with follwing properties or keys: | Property | Description | | :------------: | :------------------------------------------- | | `background` | Diagram background color (default: white) | | `fill_color` | Fill color for solid shapes (default: black) | | `font_family` | Text font (default: monospace) | | `font_size` | Text font size (default 14) | | `scale` | Diagram scale (default: 1) | | `stroke_width` | Stroke width for all lines (default: 2) | When using conversion projects instantiated by `New-StaticHTMLSiteProject` these parameters are usually configured in `Build.json` in section `svgbob` and this parameter should be omitted for these configurations to take effect. **Note**: If this parameter is specified, it superseeds the configuration from `Build.json`. .INPUTS HTML fragment objects emitted by `Convert-MarkdownToHTMLFragment` with the `-Split` switch or equivalent objects. .OUTPUTS Lines of Markdown text where all fenced code blocks labelled `bob` are replaced by Markdown style image links to svg files. .EXAMPLE PS> Convert-MarkdownToHTMLFragment -InputObject $md -Split | Convert-SvgbobToSvg -SiteDirectory $site -RelativePath $relativePath Read Markdown content from the file `$md` and replace all fenced code blocks marled as `bob` with Markdown style image links to the svg version of the diagram. The conversion is performed using default svg rendering options. Where `$site` : Is the **absolute path** to the HTML site's root directory `$relativePath` : is the **relative path** of the HTML file currently being assembled below `$site`. `$md` : is a Markdown file `test.md` which contains a fenced svgbob diagram: ``` Markdown Some text ... ~~~ bob +------+ .-. +---+ o----| elem |--( ; )--| n |----o +------+ '-' +---+ ~~~ Some more text ... ``` this fragment is converted to: * A file `test1.svg` which is placed right next to the html file `test.html` which is going to be created by `Publish-StaticHtmlSite` in a subsequent stage of the conversion pipeline. The numerical postfix is the index of the Svgbob diagram in the fragment. The svg image renders as: ~~~ bob +------+ .-. +---+ o----| elem |--( ; )--| n |----o +------+ '-' +---+ ~~~ * An updated html fragment where the fenced Svgbob diagram is replaced with a reference to the svg image. ~~~ html Some text ... <img src='test1.svg' alt='Diagram 1.' /> Some more text ... ~~~ .NOTES The svg conversion is performed by the external utility `svgbob_cli.exe` which is packaged with this module. This is a [Rust](https://www.rust-lang.org/) [crate](https://doc.rust-lang.org/rust-by-example/crates.html) which can be installed from [lib.rs](https://lib.rs/crates/svgbob_cli). .LINK https://wethat.github.io/MarkdownToHtml/2.7/Convert-SvgbobToSvg.html .LINK [Svgbob](https://ivanceras.github.io/content/Svgbob.html) #> function Convert-SvgbobToSvg { [OutputType([hashtable])] [CmdletBinding()] param( [parameter(Mandatory=$true,ValueFromPipeline=$true)] [ValidateScript({$_.HtmlFragment})] [Alias('HtmlFragment')] [hashtable]$InputObject, [parameter(Mandatory=$true,ValueFromPipeline=$false)] [string]$SiteDirectory, [parameter(Mandatory=$false,ValueFromPipeline=$false)] [object]$Options ) Begin { # svgbob default options [string]$background = 'white' [string]$fillColor = 'black' $fontSize = 14; [string]$fontFamily = 'Monospace' $scale = 1 $strokeWidth = 2 if (!$Options -and ($cfg = $InputObject.EffectiveConfiguration)) { # Check the effective configuration for options $Options = $cfg.svgbob } # override with specified options if ($Options) { $value=$Options.background if ($value) { $background = $value } $value=$Options.fill_color if ($value) { $fillColor = $value } $value=$options.font_size if ($value) { $fontSize = $value } $value=$options.font_family if ($value) { $fontFamily = $value } $value=$options.scale if ($value) { $scale = $value } $value=$options.stroke_width if ($value) { $strokeWidth = $value } } } Process { if (!$Options -and ($cfg = $InputObject.EffectiveConfiguration)) { # Update options from effective config $opts = $cfg.svgbob # override with specified options $value=$opts.background if ($value) { $background = $value } $value=$opts.fill_color if ($value) { $fillColor = $value } $value=$opts.font_size if ($value) { $fontSize = $value } $value=$opts.font_family if ($value) { $fontFamily = $value } $value=$opts.scale if ($value) { $scale = $value } $value=$opts.stroke_width if ($value) { $strokeWidth = $value } } $n = 0 $bob = $null [System.IO.Fileinfo]$fullpath = Join-Path $SiteDirectory $_.RelativePath $fragment = $InputObject.HtmlFragment for($i=0; $i -lt $fragment.Count; $i++) { $itm = $fragment[$i] if ($bob -is [Array]) { if ($itm -eq '</code>') { # svgbob drawing complete $n++ $svgname = $fullpath.BaseName + "$n.svg" # replace the fenced code block by a hyperlink $fragment[$i] = "<img src='$svgname' alt='Diagram ${n}.' />" # we need to create that site directory upfront so that the # svg image can be put there if (!$fullpath.Directory.Exists) { $fullpath.Directory.Create() } $svgfullpath = Join-Path $fullpath.DirectoryName $svgname # do the conversion $bob | & $SCRIPT:svgbob -o "$svgfullpath" ` --background $background ` --fill-color $fillColor ` --font-family $fontFamily ` --font-size $fontSize ` --scale $scale ` --stroke-width $strokeWidth $bob = $null # starting over } else { $bob += [System.Net.WebUtility]::HtmlDecode($itm.TrimEnd()) $fragment[$i] = [string]::Empty } } elseif ($itm -eq '<code class="language-bob">') { $fragment[$i] = [string]::Empty $bob=@() # Enable capturing of svgbob drawing } } $InputObject } } <# .SYNOPSIS Convert Markdown text to HTML fragments. .DESCRIPTION Converts Markdown text to HTML fragments using configured [Markdown extensions](about_MarkdownToHTML.md#supported-markdown-extensions). .PARAMETER InputObject The input object can have one of the following types: * An annotated `[System.IO.FileInfo]` object as emitted by `Find-MarkdownFiles`. * A plain markdown string [`string`]. * A markdown descriptor object which is a [`hashtable`] with following contents: | Key | Value Type | Description | | :----------------------- | :----------------- | :------------------------------------------------------------ | | `Markdown` | [`string`] | The markdown text. | | `RelativePath` | [`string`] | Relative path of the Markdown file below the input directory. | | `EffectiveConfiguration` | [`PSCustomObject`] | Optional: Build configuration in effect for this fragment | .PARAMETER IncludeExtension Comma separated list of Markdown parsing extension names. See [Markdown extensions](about_MarkdownToHTML.md#supported-markdown-extensions) for an annotated list of supported extensions. .PARAMETER ExcludeExtension Comma separated list of Markdown parsing extensions to exclude. Mostly used when the the 'advanced' parsing option is included and certain individual options need to be removed. .PARAMETER Split Split the Html fragment into an Array where each tag is in a separate slot. This somewhat simplifies Html fragment post-processing. For example the fragment ~~~ html <pre><code class="language-PowerShell">PS> Install-Module -Name MarkdownToHTML</pre></code> ~~~ is split up into the array | Index | Value | | :---: | :------------------------------------------- | | 0 | `<pre>` | | 1 | `<code class="language-PowerShell">` | | 2 | `PS> Install-Module -Name MarkdownToHTML` | | 3 | `</pre>` | | 4 | `</code>` | .INPUTS Markdown text `[string]`, Markdown file `[System.IO.FileInfo]`, or a markdown descriptor `[hashtable]`. .OUTPUTS HTML fragment object with following properties: | Property | Description | | :----------------------: | :------------------------------------------------------------------ | | `Title` | Optional page title. The first heading in the Markdown content. | | `HtmlFragment` | The HTML fragment string or array generated from the Markdown text. | | `RelativePath` | Passed through from the input object, provided it exists. | | `EffectiveConfiguration` | Passed through from the input object, provided it exists. | .NOTES The conversion to HTML fragments also includes: * Changing links to Markdown files to the corresponding Html files. ~~~ Markdown [Hello World](Hello.md) ~~~ becomes: ~~~ html <a href="Hello.html"> ~~~ * HTML encoding code blocks: ~~~ Markdown ```xml <root> <thing/> </root> ``` ~~~ becomes ~~~ HTML <pre><code class="language-xml"><root> <thing/> </root> </code></pre> ~~~ which renders as ```xml <root> <thing/> </root> ``` .EXAMPLE Convert-MarkdownToHTMLFragment -Markdown '# Hello World' Returns the HTML fragment object: Name Value ---- ----- HtmlFragment <h1 id="hello-world">Hello World</h1>... Title Hello World .EXAMPLE Convert-MarkdownToHTMLFragment -Markdown '# Hello World' -Split Returns the HTML fragment object: Name Value ---- ----- HtmlFragment {<h1 id="hello-world">,Hello World,</h1>,...} Title Hello World .EXAMPLE Get-Item -LiteralPath "Convert-MarkdownToHTML.md" | Convert-MarkdownToHTMLFragment Reads the content of Markdown file `Example.md` and returns a Html fragment object. Name Value ---- ----- Title Convert-MarkdownToHTML HtmlFragment <h1 id="convert-Markdowntohtml">Convert-MarkdownToHTML</h1>... RelativePath Convert-MarkdownToHTML.md .LINK https://wethat.github.io/MarkdownToHtml/2.7/Convert-MarkdownToHTMLFragment.html .LINK `Convert-MarkdownToHTML` .LINK `Convert-SvgbobToSvg` .LINK `Find-MarkdownFiles` .LINK `Publish-StaticHtmlSite` .LINK `New-HTMLTemplate` .LINK [Markdown extensions](about_MarkdownToHTML.md#supported-markdown-extensions) #> function Convert-MarkdownToHTMLFragment { [OutputType([hashtable])] [CmdletBinding()] param( [parameter(Mandatory=$true,ValueFromPipeline=$true)] [ValidateScript({$_ -is [string] -or $_ -is [System.IO.FileInfo] -or $_ -is [hashtable]})] [Alias('Markdown')] $InputObject, [parameter(Mandatory=$false,ValueFromPipeline=$false)] [string[]]$IncludeExtension = @('advanced'), [parameter(Mandatory=$false,ValueFromPipeline=$false)] [string[]]$ExcludeExtension = @(), [switch]$Split ) BEGIN { ## Determine which parser extensions to use if ($null -eq $IncludeExtension -or $IncludeExtension.Count -eq 0) { $IncludeExtension = @('common') # use _common_ extensions by default } elseif ('advanced' -in $IncludeExtension) { if ($ExcludeExtension.Count -gt 0) { $IncludeExtension = $IncludeExtension | Where-Object { $_ -ne 'advanced'} ## add the extensions explicitely so that we can remove individual ones $IncludeExtension += $SCRIPT:advancedMarkdownExtensions } elseif ($IncludeExtension.Count -gt 1) { $IncludeExtension = $IncludeExtension | Where-Object { $_ -ne 'advanced'} ## make sure the advanced option comes last $IncludeExtension += 'advanced' } } ## make sure the 'attributes' extension is last if ('attributes' -in $IncludeExtension) { $IncludeExtension = $IncludeExtension | Where-Object { $_ -ne 'attributes' } $IncludeExtension += 'attributes' } # Remove the excluded extensions $IncludeExtension = $IncludeExtension | Where-Object { $_ -notin $ExcludeExtension} # configure the converter pipeline [Markdig.MarkdownPipelineBuilder]$pipelineBuilder = (New-Object Markdig.MarkdownPipelineBuilder) Write-Verbose "Using parser extensions $IncludeExtension" $pipelineBuilder = [Markdig.MarkDownExtensions]::Configure($pipelineBuilder,[string]::Join('+',$IncludeExtension)) $pipeline = $pipelineBuilder.Build() } PROCESS { [string]$md = if ($InputObject -is [System.IO.FileInfo]) { Get-Content -LiteralPath $InputObject.FullName -Encoding UTF8 | Out-String } elseif ($InputObject -is [hashtable]) { $InputObject.Markdown } else { $InputObject } # Create HTML fragment and split it at tag level. # |----------| <- Html tag $fragment = [Markdig.Markdown]::ToHtml($md, $pipeline) -split '(<[^<>]+>)' | Where-Object { $_ } # update local markdown links to make them point to HTML for($i=0; $i -lt $fragment.Count; $i++) { $itm = $fragment[$i] if ($itm.StartsWith('<a') -and $itm -notlike '*://*') { $fragment[$i] = $SCRIPT:mdhrefRE.Replace($itm,'$1.html') } } if (!$Split) { # make it one string $fragment = $fragment -join '' } # assemble the descriptor object $htmlDescriptor = @{'HtmlFragment' = $fragment } $match = [regex]::Match($md,'^[#\s]*([^\r\n\{]+)') if ($match.Success) { $htmlDescriptor.Title = $match.Groups[1].Value # first heading } elseif ($InputObject.BaseName) { $htmlDescriptor.Title = $InputObject.BaseName } if ($InputObject.RelativePath) { $htmlDescriptor.RelativePath = $InputObject.RelativePath } elseif ($InputObject.Name) { $htmlDescriptor.RelativePath = $InputObject.Name } if ($InputObject.EffectiveConfiguration) { $htmlDescriptor.EffectiveConfiguration = $InputObject.EffectiveConfiguration } # return the annotated HTML fragment $htmlDescriptor } } # SIG # Begin signature block # MIIFYAYJKoZIhvcNAQcCoIIFUTCCBU0CAQExCzAJBgUrDgMCGgUAMGkGCisGAQQB # gjcCAQSgWzBZMDQGCisGAQQBgjcCAR4wJgIDAQAABBAfzDtgWUsITrck0sYpfvNR # AgEAAgEAAgEAAgEAAgEAMCEwCQYFKw4DAhoFAAQU1x0FY9OYOltBg3r7GlLhdB0r # VzugggMAMIIC/DCCAeSgAwIBAgIQaejvMGXYIKhALoN4OCBcKjANBgkqhkiG9w0B # AQUFADAVMRMwEQYDVQQDDApXZXRIYXQgTGFiMCAXDTIwMDUwMzA4MTMwNFoYDzIw # NTAwNTAzMDgyMzA0WjAVMRMwEQYDVQQDDApXZXRIYXQgTGFiMIIBIjANBgkqhkiG # 9w0BAQEFAAOCAQ8AMIIBCgKCAQEArNo5GzE4BkP8HagZLFT7h189+EPxP0pmiSC5 # yi34ZctnpyFUz+Cv547+MvzAr0uRuLkxn6ArBkVLeHVAB58jenSeLwDFls5gS0I+ # pRJWO9eyyT64EcUSCMlfMLW2q1hzjfFckFR6iFnGp3TkE0s1kQANUNjAR9axC6ju # 4dpilIupCHW+/0s9aGz7LYuRQGcy3uIL9TURKdBtOsMOBeclUsEoFSEp/0D30E8r # PNk/VLu57G5H9n3HuX/DSBR2CL8LzOOv981hiS+SCds/pHqjCX9Qj+j47Kv7xZ1i # ha2fg4AEHDGbL/WJGnTpUKath+EmgmFRlsP7PgnZr4anvGdcdQIDAQABo0YwRDAO # BgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwMwHQYDVR0OBBYEFKtE # 8xMwn4kGbe8AzXY0ineK5ToHMA0GCSqGSIb3DQEBBQUAA4IBAQAgaUJkHD9192H7 # OUhf9W3gR0ZkApD5fnPqsIgS91JFQ2fCnonudJinwbODs01yA55uUw4GJUnAKQOx # 6auVAC5KVzE2dMDbOrBOseoKj12EbzbF509FkVoT5O77NDpFrGErR1zmQ8fd1DXw # FAFC1x1vpxW7/F6g+xewpqlFKzjkPeEvLgyoUmKMCOnT0JdXS0BfyAyyIfHwvILo # 2eJWVG2UMioKOJ6vsttTu8mQgVZlfcoF6r81ee3hTEK24aHNR+frHmyrL9UplZxD # AuoUGVzYdDyOejlLPm+d+ew1d6dTf9QfurRxoKgI6OMOVI3iIIXd6HTiIW4ACwI9 # iUjry3dVMYIByjCCAcYCAQEwKTAVMRMwEQYDVQQDDApXZXRIYXQgTGFiAhBp6O8w # ZdggqEAug3g4IFwqMAkGBSsOAwIaBQCgeDAYBgorBgEEAYI3AgEMMQowCKACgACh # AoAAMBkGCSqGSIb3DQEJAzEMBgorBgEEAYI3AgEEMBwGCisGAQQBgjcCAQsxDjAM # BgorBgEEAYI3AgEVMCMGCSqGSIb3DQEJBDEWBBSbpQy+3iSZ2r5yxqmP7xKoH7KZ # KzANBgkqhkiG9w0BAQEFAASCAQCEME4VEd/nInPHakNR8kGw4fKRHLpG/sCpihjn # BDg/mbQd3IRJTRUUSMFGI93HVFPjnGAN6p7ytUFuCKQuWRqPzyWO5qyIwJl6T3Tf # 3gYI96Lm//LNRbWKSkqEKyfqii3zud+NvkP0EtJYxYM/a3NK1QLiaAQkEHHY16P1 # bO3nLOmO1t9c5zb63ZaK6mrrW894jEqXlHQ4mPsKlvcuPYMcIAYlUTUObWHSi2Rc # z1/9hmPSg6rKabplSpVFWhfx+QoTiOnHPcmd0A5bgzC8an8wsdumAzWBd+MzWzcR # AJ+VqHBueVLsPX9HrrGk+54EPb+ctd/uCOB87i0VCorUU4HO # SIG # End signature block |