mirror of https://github.com/raandree/NTFSSecurity
Browse Source
- .github/scripts/Export-WikiContent.ps1 converts Docs, except the contributor guide, into flat wiki pages: Docs/README.md becomes Home, cmdlet pages lose their platyPS metadata, links point to wiki pages or to the files on GitHub, and links in code stay unchanged. It writes a sidebar from the cmdlet groups of Docs/README.md, a footer, and the former page How-to-install, and keeps the page name Version-History that the release notes link to. - Tests/Wiki.Tests.ps1 checks the conversion rules with a sample of Docs and every link and anchor of the wiki generated from the real Docs. - README, CHANGELOG, and the version history mention the wiki again. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant <ai@example.com>pull/96/head
Raimund Andree
1 week ago
5 changed files with 519 additions and 2 deletions
@ -0,0 +1,279 @@ |
|||||
|
<# |
||||
|
.SYNOPSIS |
||||
|
Converts the documentation in the Docs folder into the pages of the GitHub wiki. |
||||
|
|
||||
|
.DESCRIPTION |
||||
|
Writes a wiki page for every page in Docs except the contributor guide (Contributing.md and the Contributing |
||||
|
folder). Docs/README.md becomes the page Home, and every other page keeps its file name, so a page in |
||||
|
Docs/Cmdlets becomes a page named after its cmdlet. The platyPS metadata at the top of the cmdlet pages is |
||||
|
removed. Relative links point to the wiki pages; links to other files of the repository point to the files on |
||||
|
GitHub. Links in code stay unchanged. |
||||
|
|
||||
|
The script also writes the sidebar, which lists the cmdlets in the groups of the cmdlet list in Docs/README.md; |
||||
|
the footer; and the page How-to-install, which keeps the address of the former wiki page working. |
||||
|
|
||||
|
The script removes everything in DestinationPath except the .git folder, so that pages that no longer exist in |
||||
|
Docs disappear from the wiki. |
||||
|
|
||||
|
.PARAMETER Path |
||||
|
Specifies the Docs folder of the repository. |
||||
|
|
||||
|
.PARAMETER DestinationPath |
||||
|
Specifies the folder to write the wiki pages to, usually a clone of the wiki repository. The script creates the |
||||
|
folder if it doesn't exist. |
||||
|
|
||||
|
.PARAMETER RepositoryUrl |
||||
|
Specifies the address of the repository on GitHub, for links to files that aren't wiki pages. |
||||
|
|
||||
|
.PARAMETER Branch |
||||
|
Specifies the branch for links to files that aren't wiki pages. |
||||
|
|
||||
|
.EXAMPLE |
||||
|
git clone https://github.com/raandree/NTFSSecurity.wiki.git $env:TEMP\wiki |
||||
|
.\.github\scripts\Export-WikiContent.ps1 -Path .\Docs -DestinationPath $env:TEMP\wiki |
||||
|
git -C $env:TEMP\wiki status |
||||
|
|
||||
|
Writes the wiki pages into a clone of the wiki and shows which pages change. |
||||
|
#> |
||||
|
[CmdletBinding(SupportsShouldProcess)] |
||||
|
param ( |
||||
|
[Parameter(Mandatory)] |
||||
|
[ValidateScript({ Test-Path -LiteralPath $_ -PathType Container })] |
||||
|
[string] |
||||
|
$Path, |
||||
|
|
||||
|
[Parameter(Mandatory)] |
||||
|
[ValidateNotNullOrEmpty()] |
||||
|
[string] |
||||
|
$DestinationPath, |
||||
|
|
||||
|
[Parameter()] |
||||
|
[ValidateNotNullOrEmpty()] |
||||
|
[string] |
||||
|
$RepositoryUrl = 'https://github.com/raandree/NTFSSecurity', |
||||
|
|
||||
|
[Parameter()] |
||||
|
[ValidateNotNullOrEmpty()] |
||||
|
[string] |
||||
|
$Branch = 'master' |
||||
|
) |
||||
|
|
||||
|
$ErrorActionPreference = 'Stop' |
||||
|
|
||||
|
function Resolve-RepositoryPath { |
||||
|
<# |
||||
|
Returns the path of a link target relative to the repository root, with / as separator, or nothing if the |
||||
|
link leaves the repository. |
||||
|
#> |
||||
|
param ( |
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Directory, |
||||
|
|
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Link |
||||
|
) |
||||
|
|
||||
|
$segments = New-Object -TypeName 'System.Collections.Generic.List[string]' |
||||
|
foreach ($segment in (('{0}/{1}' -f $Directory, $Link) -split '/')) { |
||||
|
if ($segment -eq '..') { |
||||
|
if ($segments.Count -eq 0) { |
||||
|
return |
||||
|
} |
||||
|
$segments.RemoveAt($segments.Count - 1) |
||||
|
} elseif ($segment -and $segment -ne '.') { |
||||
|
$segments.Add($segment) |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
$segments -join '/' |
||||
|
} |
||||
|
|
||||
|
function ConvertTo-WikiLink { |
||||
|
<# |
||||
|
Returns the wiki address of a link on a page in Directory: the name of a wiki page, the address of a file of |
||||
|
the repository on GitHub, or the link itself if it is absolute or points to the same page. |
||||
|
#> |
||||
|
param ( |
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Url, |
||||
|
|
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Directory |
||||
|
) |
||||
|
|
||||
|
if ($Url -match '^(?:[a-zA-Z][a-zA-Z0-9+.-]*:|//|#)') { |
||||
|
return $Url |
||||
|
} |
||||
|
|
||||
|
$linkPath, $anchor = $Url -split '#', 2 |
||||
|
$target = Resolve-RepositoryPath -Directory $Directory -Link ([uri]::UnescapeDataString($linkPath)) |
||||
|
if (-not $target) { |
||||
|
return $Url |
||||
|
} |
||||
|
|
||||
|
$fragment = if ($anchor) { '#' + $anchor } else { '' } |
||||
|
if ($pageNames.ContainsKey($target)) { |
||||
|
return $pageNames[$target] + $fragment |
||||
|
} |
||||
|
|
||||
|
$view = if (Test-Path -LiteralPath (Join-Path -Path $repositoryRoot -ChildPath $target) -PathType Container) { |
||||
|
'tree' |
||||
|
} else { |
||||
|
'blob' |
||||
|
} |
||||
|
'{0}/{1}/{2}/{3}{4}' -f $RepositoryUrl.TrimEnd('/'), $view, $Branch, $target, $fragment |
||||
|
} |
||||
|
|
||||
|
function Convert-MarkdownLink { |
||||
|
<# |
||||
|
Returns the Markdown text with the links of a page in Directory converted to wiki addresses. Links in code |
||||
|
spans and fenced code blocks stay unchanged. |
||||
|
#> |
||||
|
[Diagnostics.CodeAnalysis.SuppressMessageAttribute( |
||||
|
'PSReviewUnusedParameter', 'Directory', Justification = 'The match evaluator script block uses it.' |
||||
|
)] |
||||
|
param ( |
||||
|
[Parameter(Mandatory)] |
||||
|
[AllowEmptyString()] |
||||
|
[string] |
||||
|
$Markdown, |
||||
|
|
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Directory |
||||
|
) |
||||
|
|
||||
|
$inlinePattern = '(?<code>(?<ticks>`+).+?\k<ticks>)|(?<prefix>!?\[(?:[^\[\]`]|`[^`]*`)*\]\()(?<url>[^)\s]+)(?<suffix>(?:\s+"[^"]*")?\))' |
||||
|
$definitionPattern = '^(?<prefix>\s{0,3}\[[^\]]+\]:\s*)(?<url>\S+)(?<suffix>.*)$' |
||||
|
$convertLink = { |
||||
|
param ($match) |
||||
|
|
||||
|
if ($match.Groups['code'].Success) { |
||||
|
return $match.Value |
||||
|
} |
||||
|
$match.Groups['prefix'].Value + (ConvertTo-WikiLink -Url $match.Groups['url'].Value -Directory $Directory) + |
||||
|
$match.Groups['suffix'].Value |
||||
|
} |
||||
|
|
||||
|
$fence = $null |
||||
|
$lines = foreach ($line in ($Markdown -split '\r?\n')) { |
||||
|
if ($line -match '^\s{0,3}(?<fence>`{3,}|~{3,})') { |
||||
|
if (-not $fence) { |
||||
|
$fence = $Matches['fence'] |
||||
|
} elseif ($Matches['fence'].StartsWith($fence)) { |
||||
|
$fence = $null |
||||
|
} |
||||
|
$line |
||||
|
continue |
||||
|
} |
||||
|
if ($fence) { |
||||
|
$line |
||||
|
continue |
||||
|
} |
||||
|
|
||||
|
$line = [regex]::Replace($line, $inlinePattern, $convertLink) |
||||
|
[regex]::Replace($line, $definitionPattern, $convertLink) |
||||
|
} |
||||
|
|
||||
|
$lines -join "`n" |
||||
|
} |
||||
|
|
||||
|
$docsRoot = (Resolve-Path -LiteralPath $Path).ProviderPath.TrimEnd('\', '/') |
||||
|
$repositoryRoot = Split-Path -Path $docsRoot -Parent |
||||
|
$docsName = Split-Path -Path $docsRoot -Leaf |
||||
|
$destinationRoot = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($DestinationPath).TrimEnd('\', '/') |
||||
|
|
||||
|
# Refuse a destination that contains the documentation, such as the repository itself. |
||||
|
$separator = [IO.Path]::DirectorySeparatorChar |
||||
|
if (($docsRoot + $separator).StartsWith($destinationRoot + $separator, [StringComparison]::OrdinalIgnoreCase)) { |
||||
|
throw "The destination '$destinationRoot' contains the documentation in '$docsRoot'. Specify a clone of the wiki." |
||||
|
} |
||||
|
|
||||
|
# Collect the pages: Docs/README.md is the home page, and the contributor guide stays in the repository. |
||||
|
$pageNames = @{} |
||||
|
$pages = foreach ($file in Get-ChildItem -LiteralPath $docsRoot -Filter '*.md' -File -Recurse) { |
||||
|
$repositoryPath = $file.FullName.Substring($repositoryRoot.Length + 1) -replace '\\', '/' |
||||
|
if ($repositoryPath -match ('^{0}/Contributing(?:\.md$|/)' -f [regex]::Escape($docsName))) { |
||||
|
continue |
||||
|
} |
||||
|
|
||||
|
$name = if ($repositoryPath -eq "$docsName/README.md") { 'Home' } else { $file.BaseName } |
||||
|
if ($pageNames.Values -contains $name) { |
||||
|
throw "Two pages in '$docsRoot' would become the wiki page '$name'." |
||||
|
} |
||||
|
$pageNames[$repositoryPath] = $name |
||||
|
|
||||
|
$content = Get-Content -LiteralPath $file.FullName -Raw -Encoding UTF8 |
||||
|
$title = if ($content -match '(?m)^#\s+(?<title>.+?)\s*$') { $Matches['title'] } else { $name -replace '-', ' ' } |
||||
|
[pscustomobject]@{ |
||||
|
Name = $name |
||||
|
Title = $title |
||||
|
Directory = $repositoryPath.Substring(0, $repositoryPath.LastIndexOf('/')) |
||||
|
Content = $content |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
# Remove the old pages, but keep the history of the wiki. |
||||
|
if (Test-Path -LiteralPath $destinationRoot) { |
||||
|
foreach ($item in Get-ChildItem -LiteralPath $destinationRoot -Force | Where-Object -Property Name -NE -Value '.git') { |
||||
|
if ($PSCmdlet.ShouldProcess($item.FullName, 'Remove')) { |
||||
|
Remove-Item -LiteralPath $item.FullName -Recurse -Force |
||||
|
} |
||||
|
} |
||||
|
} elseif ($PSCmdlet.ShouldProcess($destinationRoot, 'Create folder')) { |
||||
|
New-Item -ItemType Directory -Path $destinationRoot | Out-Null |
||||
|
} |
||||
|
|
||||
|
$wikiPages = [ordered]@{} |
||||
|
foreach ($page in $pages) { |
||||
|
$content = [regex]::Replace($page.Content, '\A---\r?\n.*?\r?\n---[ \t]*(?:\r?\n|\z)\s*', '', 'Singleline') |
||||
|
$wikiPages[$page.Name] = Convert-MarkdownLink -Markdown $content -Directory $page.Directory |
||||
|
} |
||||
|
|
||||
|
# The sidebar links the other pages and the cmdlets, grouped like the cmdlet list of the home page. |
||||
|
$homePage = $pages | Where-Object -Property Name -EQ -Value 'Home' |
||||
|
$sidebar = New-Object -TypeName 'System.Collections.Generic.List[string]' |
||||
|
$sidebar.Add('### [Home](Home)') |
||||
|
$sidebar.Add('') |
||||
|
foreach ($page in $pages | Where-Object { $_.Directory -eq $docsName -and $_.Name -ne 'Home' } | Sort-Object -Property Name) { |
||||
|
$sidebar.Add(('- [{0}]({1})' -f $page.Title, $page.Name)) |
||||
|
} |
||||
|
if ($homePage) { |
||||
|
$section = $null |
||||
|
foreach ($line in ($homePage.Content -split '\r?\n')) { |
||||
|
if ($line -match '^##\s+(?<title>.+?)\s*$') { |
||||
|
$section = $Matches['title'] |
||||
|
if ($section -eq 'Cmdlets') { |
||||
|
$sidebar.Add('') |
||||
|
$sidebar.Add('### Cmdlets') |
||||
|
} |
||||
|
} elseif ($section -eq 'Cmdlets' -and $line -match '^###\s+(?<title>.+?)\s*$') { |
||||
|
$sidebar.Add('') |
||||
|
$sidebar.Add(('**{0}**' -f $Matches['title'])) |
||||
|
$sidebar.Add('') |
||||
|
} elseif ($section -eq 'Cmdlets' -and $line -match '^\|\s*\[(?<name>[^\]]+)\]\((?<url>[^)\s]+)\)') { |
||||
|
$sidebar.Add(('- [{0}]({1})' -f $Matches['name'], (ConvertTo-WikiLink -Url $Matches['url'] -Directory $docsName))) |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
$wikiPages['_Sidebar'] = $sidebar -join "`n" |
||||
|
|
||||
|
$wikiPages['_Footer'] = ('This wiki is generated from the [{0}]({1}/tree/{2}/{0}) folder of the repository. ' + |
||||
|
'To change a page, edit its file there; changes made in the wiki are overwritten.') -f $docsName, $RepositoryUrl.TrimEnd('/'), $Branch |
||||
|
|
||||
|
# The former wiki page How-to-install is linked from outside; it now points to the installation steps. |
||||
|
if ($homePage -and $homePage.Content -match '(?m)^##\s+Installation\s*$') { |
||||
|
$wikiPages['How-to-install'] = "# How to install`n`nThe installation steps are in the [Installation](Home#installation) section of the [Home](Home) page." |
||||
|
} |
||||
|
|
||||
|
$encoding = New-Object -TypeName 'System.Text.UTF8Encoding' -ArgumentList $false |
||||
|
foreach ($name in $wikiPages.Keys) { |
||||
|
$file = Join-Path -Path $destinationRoot -ChildPath "$name.md" |
||||
|
if ($PSCmdlet.ShouldProcess($file, 'Write wiki page')) { |
||||
|
[IO.File]::WriteAllText($file, $wikiPages[$name].TrimEnd() + "`n", $encoding) |
||||
|
} |
||||
|
} |
||||
@ -0,0 +1,228 @@ |
|||||
|
<# |
||||
|
Tests .github\scripts\Export-WikiContent.ps1, which converts the documentation in Docs into the pages of the |
||||
|
GitHub wiki: with a small sample of Docs for the conversion rules, and with the real Docs for complete pages and |
||||
|
working links. |
||||
|
#> |
||||
|
[Diagnostics.CodeAnalysis.SuppressMessageAttribute( |
||||
|
'PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Pester shares variables between blocks.' |
||||
|
)] |
||||
|
param () |
||||
|
|
||||
|
BeforeAll { |
||||
|
$exportScript = Join-Path -Path $PSScriptRoot -ChildPath '..\.github\scripts\Export-WikiContent.ps1' |
||||
|
|
||||
|
function Get-GitHubAnchor { |
||||
|
# Returns the anchors that GitHub generates for the headings of a Markdown text. |
||||
|
param ( |
||||
|
[Parameter(Mandatory)] |
||||
|
[string] |
||||
|
$Markdown |
||||
|
) |
||||
|
|
||||
|
$text = [regex]::Replace($Markdown, '(?ms)^```.*?^```', '') |
||||
|
$seen = @{} |
||||
|
foreach ($match in [regex]::Matches($text, '(?m)^#{1,6}\s+(.+?)\s*#*\s*$')) { |
||||
|
$heading = $match.Groups[1].Value -replace '\[([^\]]*)\]\([^)]*\)', '$1' -replace '[`*]', '' |
||||
|
$anchor = [regex]::Replace($heading.Trim().ToLowerInvariant(), '[^\p{L}\p{Nd}\s_-]', '') -replace ' ', '-' |
||||
|
if ($seen.ContainsKey($anchor)) { |
||||
|
$seen[$anchor]++ |
||||
|
'{0}-{1}' -f $anchor, $seen[$anchor] |
||||
|
} else { |
||||
|
$seen[$anchor] = 0 |
||||
|
$anchor |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
Describe 'Export-WikiContent.ps1' { |
||||
|
Context 'When it converts a sample of Docs' { |
||||
|
BeforeAll { |
||||
|
$repositoryPath = Join-Path -Path $TestDrive -ChildPath 'repository' |
||||
|
$docsPath = Join-Path -Path $repositoryPath -ChildPath 'Docs' |
||||
|
$wikiPath = Join-Path -Path $TestDrive -ChildPath 'wiki' |
||||
|
foreach ($folder in "$docsPath\Cmdlets", "$docsPath\Contributing", "$wikiPath\.git") { |
||||
|
New-Item -ItemType Directory -Path $folder -Force | Out-Null |
||||
|
} |
||||
|
|
||||
|
# A clone of the wiki with pages that Docs doesn't have |
||||
|
Set-Content -LiteralPath "$wikiPath\.git\config" -Value '[core]' |
||||
|
Set-Content -LiteralPath "$wikiPath\Version-History.textile" -Value '* 4.2.4' |
||||
|
Set-Content -LiteralPath "$wikiPath\Old-Page.md" -Value '# Old page' |
||||
|
|
||||
|
Set-Content -LiteralPath "$repositoryPath\CHANGELOG.md" -Value '# Changelog' |
||||
|
Set-Content -LiteralPath "$docsPath\Contributing.md" -Value '# Contributing' |
||||
|
Set-Content -LiteralPath "$docsPath\Contributing\01-Getting-Started.md" -Value '# Get started' |
||||
|
Set-Content -LiteralPath "$docsPath\Concepts.md" -Value "# Concepts`n`n## Rights`n`nSee [Home](README.md)." |
||||
|
Set-Content -LiteralPath "$docsPath\README.md" -Value @' |
||||
|
# Thing |
||||
|
|
||||
|
[Concepts](Concepts.md#rights), [Get-Thing](Cmdlets/Get-Thing.md), and [`Set-Thing`](Cmdlets/Set-Thing.md). |
||||
|
[Changelog](../CHANGELOG.md), [guide](Contributing.md), and [first steps](Contributing/01-Getting-Started.md). |
||||
|
[Example site](https://example.com/page.md) and [cmdlets](#cmdlets). |
||||
|
Code keeps its links: `[Concepts](Concepts.md)`. |
||||
|
|
||||
|
```powershell |
||||
|
# [Concepts](Concepts.md) |
||||
|
``` |
||||
|
|
||||
|
## Installation |
||||
|
|
||||
|
Install the module. |
||||
|
|
||||
|
## Cmdlets |
||||
|
|
||||
|
### Getting |
||||
|
|
||||
|
| Cmdlet | Description | |
||||
|
| --- | --- | |
||||
|
| [Get-Thing](Cmdlets/Get-Thing.md) | Gets a thing. | |
||||
|
|
||||
|
### Setting |
||||
|
|
||||
|
| Cmdlet | Description | |
||||
|
| --- | --- | |
||||
|
| [Set-Thing](Cmdlets/Set-Thing.md) | Sets a thing. | |
||||
|
'@ |
||||
|
$metadata = "---`nexternal help file: Thing.dll-Help.xml`nonline version: https://example.com`nschema: 2.0.0`n---`n`n" |
||||
|
Set-Content -LiteralPath "$docsPath\Cmdlets\Get-Thing.md" -Value ($metadata + |
||||
|
"# Get-Thing`n`nSee [rights](../Concepts.md#rights), [Set-Thing](Set-Thing.md), and [home](../README.md).") |
||||
|
Set-Content -LiteralPath "$docsPath\Cmdlets\Set-Thing.md" -Value ($metadata + |
||||
|
"# Set-Thing`n`nSee [Get-Thing](Get-Thing.md).") |
||||
|
|
||||
|
& $exportScript -Path $docsPath -DestinationPath $wikiPath -RepositoryUrl 'https://github.com/contoso/Thing' -Branch 'main' |
||||
|
|
||||
|
$homePage = Get-Content -LiteralPath "$wikiPath\Home.md" -Raw |
||||
|
$sidebar = Get-Content -LiteralPath "$wikiPath\_Sidebar.md" -Raw |
||||
|
} |
||||
|
|
||||
|
It 'Should write Home, Concepts, the cmdlet pages, How-to-install, the sidebar, and the footer' { |
||||
|
$expected = 'Home.md', 'Concepts.md', 'Get-Thing.md', 'Set-Thing.md', 'How-to-install.md', '_Sidebar.md', '_Footer.md' |
||||
|
|
||||
|
((Get-ChildItem -LiteralPath $wikiPath -File).Name | Sort-Object) -join ', ' | |
||||
|
Should -BeExactly (($expected | Sort-Object) -join ', ') |
||||
|
} |
||||
|
|
||||
|
It 'Should keep the .git folder and remove the pages that Docs does not have' { |
||||
|
"$wikiPath\.git\config" | Should -Exist |
||||
|
"$wikiPath\Version-History.textile" | Should -Not -Exist |
||||
|
"$wikiPath\Old-Page.md" | Should -Not -Exist |
||||
|
} |
||||
|
|
||||
|
It 'Should not publish the contributor guide' { |
||||
|
Get-ChildItem -LiteralPath $wikiPath -Recurse -File -Filter '*Get*Started*' | Should -BeNullOrEmpty |
||||
|
"$wikiPath\Contributing.md" | Should -Not -Exist |
||||
|
} |
||||
|
|
||||
|
It 'Should convert <Link> on <Page> into <Expected>' -ForEach @( |
||||
|
@{ Page = 'Home'; Link = '[Concepts](Concepts.md#rights)'; Expected = '[Concepts](Concepts#rights)' } |
||||
|
@{ Page = 'Home'; Link = '[Get-Thing](Cmdlets/Get-Thing.md)'; Expected = '[Get-Thing](Get-Thing)' } |
||||
|
@{ Page = 'Home'; Link = '[`Set-Thing`](Cmdlets/Set-Thing.md)'; Expected = '[`Set-Thing`](Set-Thing)' } |
||||
|
@{ Page = 'Home'; Link = '[Changelog](../CHANGELOG.md)'; Expected = '[Changelog](https://github.com/contoso/Thing/blob/main/CHANGELOG.md)' } |
||||
|
@{ Page = 'Home'; Link = '[guide](Contributing.md)'; Expected = '[guide](https://github.com/contoso/Thing/blob/main/Docs/Contributing.md)' } |
||||
|
@{ Page = 'Home'; Link = '[first steps](Contributing/01-Getting-Started.md)'; Expected = '[first steps](https://github.com/contoso/Thing/blob/main/Docs/Contributing/01-Getting-Started.md)' } |
||||
|
@{ Page = 'Home'; Link = '[Example site](https://example.com/page.md)'; Expected = '[Example site](https://example.com/page.md)' } |
||||
|
@{ Page = 'Home'; Link = '[cmdlets](#cmdlets)'; Expected = '[cmdlets](#cmdlets)' } |
||||
|
@{ Page = 'Concepts'; Link = '[Home](README.md)'; Expected = '[Home](Home)' } |
||||
|
@{ Page = 'Get-Thing'; Link = '[rights](../Concepts.md#rights)'; Expected = '[rights](Concepts#rights)' } |
||||
|
@{ Page = 'Get-Thing'; Link = '[Set-Thing](Set-Thing.md)'; Expected = '[Set-Thing](Set-Thing)' } |
||||
|
@{ Page = 'Get-Thing'; Link = '[home](../README.md)'; Expected = '[home](Home)' } |
||||
|
) { |
||||
|
$content = Get-Content -LiteralPath "$wikiPath\$Page.md" -Raw |
||||
|
|
||||
|
$content | Should -Match ([regex]::Escape($Expected)) |
||||
|
if ($Link -ne $Expected) { |
||||
|
$content | Should -Not -Match ([regex]::Escape($Link)) |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
It 'Should keep links in code unchanged' { |
||||
|
$homePage | Should -Match ([regex]::Escape('`[Concepts](Concepts.md)`')) |
||||
|
$homePage | Should -Match ([regex]::Escape('# [Concepts](Concepts.md)')) |
||||
|
} |
||||
|
|
||||
|
It 'Should remove the platyPS metadata from the cmdlet pages' { |
||||
|
Get-Content -LiteralPath "$wikiPath\Get-Thing.md" -TotalCount 1 | Should -BeExactly '# Get-Thing' |
||||
|
} |
||||
|
|
||||
|
It 'Should link Home and the other pages in the sidebar' { |
||||
|
$sidebar | Should -Match ([regex]::Escape('[Home](Home)')) |
||||
|
$sidebar | Should -Match ([regex]::Escape('[Concepts](Concepts)')) |
||||
|
} |
||||
|
|
||||
|
It 'Should list the cmdlets in the sidebar under the groups of Docs/README.md' { |
||||
|
$sidebar | Should -Match '(?s)Getting.*\[Get-Thing\]\(Get-Thing\).*Setting.*\[Set-Thing\]\(Set-Thing\)' |
||||
|
} |
||||
|
|
||||
|
It 'Should say in the footer that the wiki is generated from Docs' { |
||||
|
Get-Content -LiteralPath "$wikiPath\_Footer.md" -Raw | |
||||
|
Should -Match ([regex]::Escape('(https://github.com/contoso/Thing/tree/main/Docs)')) |
||||
|
} |
||||
|
|
||||
|
It 'Should keep the address of the former page How-to-install' { |
||||
|
Get-Content -LiteralPath "$wikiPath\How-to-install.md" -Raw | Should -Match ([regex]::Escape('(Home#installation)')) |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
Context 'When it converts the documentation of the repository' { |
||||
|
BeforeAll { |
||||
|
$repositoryPath = Join-Path -Path $PSScriptRoot -ChildPath '..' |
||||
|
$docsPath = Join-Path -Path $repositoryPath -ChildPath 'Docs' |
||||
|
$wikiPath = Join-Path -Path $TestDrive -ChildPath 'wiki-of-the-repository' |
||||
|
|
||||
|
& $exportScript -Path $docsPath -DestinationPath $wikiPath |
||||
|
|
||||
|
$pages = Get-ChildItem -LiteralPath $wikiPath -Filter '*.md' |
||||
|
$cmdletNames = (Get-ChildItem -LiteralPath (Join-Path -Path $docsPath -ChildPath 'Cmdlets') -Filter '*.md').BaseName |
||||
|
} |
||||
|
|
||||
|
It 'Should write a page for every page in Docs except the contributor guide, and one for every cmdlet' { |
||||
|
$topPages = (Get-ChildItem -LiteralPath $docsPath -Filter '*.md' | |
||||
|
Where-Object -Property Name -NotIn -Value 'README.md', 'Contributing.md').BaseName |
||||
|
$expected = @('Home', 'How-to-install', '_Sidebar', '_Footer') + $topPages + $cmdletNames |
||||
|
|
||||
|
($pages.BaseName | Sort-Object) -join ', ' | Should -BeExactly (($expected | Sort-Object) -join ', ') |
||||
|
} |
||||
|
|
||||
|
It 'Should keep the page name Version-History, which the release notes of 4.2.4 and 4.2.6 link to' { |
||||
|
Join-Path -Path $wikiPath -ChildPath 'Version-History.md' | Should -Exist |
||||
|
} |
||||
|
|
||||
|
It 'Should list every cmdlet in the sidebar' { |
||||
|
$sidebar = Get-Content -LiteralPath (Join-Path -Path $wikiPath -ChildPath '_Sidebar.md') -Raw |
||||
|
|
||||
|
$cmdletNames | Where-Object -FilterScript { $sidebar -notmatch ('\]\({0}\)' -f [regex]::Escape($_)) } | |
||||
|
Should -BeNullOrEmpty |
||||
|
} |
||||
|
|
||||
|
It 'Should link only to existing wiki pages, their anchors, and existing files of the repository' { |
||||
|
$anchors = @{} |
||||
|
foreach ($page in $pages) { |
||||
|
$anchors[$page.BaseName] = @(Get-GitHubAnchor -Markdown (Get-Content -LiteralPath $page.FullName -Raw)) |
||||
|
} |
||||
|
|
||||
|
$brokenLinks = foreach ($page in $pages) { |
||||
|
$text = [regex]::Replace((Get-Content -LiteralPath $page.FullName -Raw), '(?ms)^```.*?^```', '') |
||||
|
$text = [regex]::Replace($text, '`[^`\n]+`', '') |
||||
|
foreach ($match in [regex]::Matches($text, '\]\((?<url>[^)\s]+)\)')) { |
||||
|
$url = $match.Groups['url'].Value |
||||
|
if ($url -match '^https://github\.com/raandree/NTFSSecurity/(?:blob|tree)/master/(?<path>[^#]+)') { |
||||
|
if (-not (Test-Path -LiteralPath (Join-Path -Path $repositoryPath -ChildPath $Matches['path']))) { |
||||
|
'{0}: {1}' -f $page.BaseName, $url |
||||
|
} |
||||
|
} elseif ($url -notmatch '^[a-z]+:') { |
||||
|
$target, $anchor = $url -split '#', 2 |
||||
|
if (-not $target) { |
||||
|
$target = $page.BaseName |
||||
|
} |
||||
|
if (-not $anchors.ContainsKey($target) -or ($anchor -and $anchors[$target] -notcontains $anchor)) { |
||||
|
'{0}: {1}' -f $page.BaseName, $url |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
$brokenLinks | Should -BeNullOrEmpty |
||||
|
} |
||||
|
} |
||||
|
} |
||||
Loading…
Reference in new issue