Skip to content

Commit 3c64f14

Browse files
ArlodotexeArlodotexe
committed
Refactor markdown processing and TOC generation
1 parent 53e865c commit 3c64f14

File tree

1 file changed

+99
-65
lines changed

1 file changed

+99
-65
lines changed

‎Build-Toolkit-Docs.ps1

Lines changed: 99 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -5,84 +5,118 @@ Param (
55

66
$tocContents = "items:`n"
77

8-
$componentsRoot = Resolve-Path $PSScriptRoot/../components/
9-
10-
# For each component
11-
foreach ($componentFolder in Get-ChildItem -Path $componentsRoot -Directory) {
12-
$componentName = $componentFolder.Name
13-
14-
# Add component to TOC
15-
$tocContents = $tocContents + "- name: $componentName`n items:`n"
16-
17-
# Find each markdown file in component's samples folder
18-
foreach ($markdownFile in Get-ChildItem -Recurse -Path "$componentFolder/samples/**/*.md" | Where-Object { $_.FullName -notlike "*\bin\*" -and $_FullName -notlike "*\obj\*" }) {
19-
$contents = Get-Content $markdownFile -Raw
20-
21-
# Find title
22-
$contents -match 'title:\s*(?<title>.*)' | Out-Null
8+
function AppendTocItem([string] $name, [int] $level, [hashtable] $properties) {
9+
$indent = " " * $level
10+
$firstLineIndent = " " * ($level - 1)
2311

24-
$header = $Matches.title
25-
26-
# Find end of YAML
27-
$endIndex = $contents | Select-String -Pattern "---" -AllMatches | ForEach-Object { $_.Matches[1].Index }
28-
29-
# Insert Header
30-
$contents = $contents.Substring(0, $endIndex + 5) + "`n# $header`n" + $contents.Substring($endIndex + 5)
12+
$lines = "$firstLineIndent- name: $name`n"
3113

32-
# Find Sample Placeholders, replace with code content
33-
foreach ($sample in ($contents | Select-String -Pattern '>\s*\[!SAMPLE\s*(?<sampleid>.*)\s*\]\s*' -AllMatches).Matches) {
34-
$sampleid = $sample.Groups[1].Value
35-
$sampleString = $sample.Groups[0].Value
14+
foreach($key in $properties.Keys) {
15+
$lines += "$indent$($key): $($properties[$key])`n"
16+
}
3617

37-
# Find matching filename for CS
38-
foreach ($csFile in Get-ChildItem -Recurse -Path ($markdownFile.DirectoryName + '\**\*.xaml.cs').Replace('\', '/') |
39-
Where-Object { $_.FullName -notlike "*\bin\*" -and $_FullName -notlike "*\obj\*" }) {
40-
$csSample = Get-Content $csFile -Raw
41-
42-
if ($csSample -match '\[ToolkitSample\s?\(\s*id:\s*(?:"|nameof\()\s?' + $sampleid + '\s?(?:"|\))') {
43-
# Get Relative Path
44-
$docPath = $(Join-Path "components" $($csfile.FullName.Replace($componentsRoot.Path, ''))).Replace('\', '/').Trim('/')
18+
return $lines
19+
}
4520

46-
# See https://learn.microsoft.com/en-us/contribute/content/code-in-docs#out-of-repo-snippet-references
47-
$snippet = ':::code language="xaml" source="~/../code-windows/' + $docPath.Substring(0, $docPath.Length - 3) + '":::' + "`n`n"
21+
function GetTitleFrontMatterFromMarkdownFile($markdownFile) {
22+
$contents = Get-Content $markdownFile -Raw
23+
return GetTitleFrontMatterFromMarkdownContents $contents
24+
}
4825

49-
$snippet = $snippet + ':::code language="csharp" source="~/../code-windows/' + $docPath + '":::' + "`n`n"
26+
function GetTitleFrontMatterFromMarkdownContents($contents) {
27+
$contents -match 'title:\s*(?<title>.*)' | Out-Null
28+
return $Matches.title
29+
}
5030

51-
# Replace our Sample Placeholder with references for docs
52-
$contents = $contents.Replace($sampleString, $snippet)
53-
}
31+
function ProcessMarkdownFile($markdownFile) {
32+
$contents = Get-Content $markdownFile -Raw
33+
$header = GetTitleFrontMatterFromMarkdownContents $contents
34+
35+
# Find end of YAML
36+
$endIndex = $contents | Select-String -Pattern "---" -AllMatches | ForEach-Object { $_.Matches[1].Index }
37+
38+
# Insert Header
39+
$contents = $contents.Substring(0, $endIndex + 5) + "`n# $header`n" + $contents.Substring($endIndex + 5)
40+
41+
# Find Sample Placeholders, replace with code content
42+
foreach ($sample in ($contents | Select-String -Pattern '>\s*\[!SAMPLE\s*(?<sampleid>.*)\s*\]\s*' -AllMatches).Matches) {
43+
$sampleid = $sample.Groups[1].Value
44+
$sampleString = $sample.Groups[0].Value
45+
46+
# Find matching filename for CS
47+
foreach ($csFile in Get-ChildItem -Recurse -Path ($markdownFile.DirectoryName + '\**\*.xaml.cs').Replace('\', '/') |
48+
Where-Object { $_.FullName -notlike "*\bin\*" -and $_FullName -notlike "*\obj\*" }) {
49+
$csSample = Get-Content $csFile -Raw
50+
51+
if ($csSample -match '\[ToolkitSample\s?\(\s*id:\s*(?:"|nameof\()\s?' + $sampleid + '\s?(?:"|\))') {
52+
# Get Relative Path
53+
$docPath = $(Join-Path "components" $($csfile.FullName.Replace($componentsRoot.Path, ''))).Replace('\', '/').Trim('/')
54+
55+
# See https://learn.microsoft.com/en-us/contribute/content/code-in-docs#out-of-repo-snippet-references
56+
$snippet = ':::code language="xaml" source="~/../code-windows/' + $docPath.Substring(0, $docPath.Length - 3) + '":::' + "`n`n"
57+
58+
$snippet = $snippet + ':::code language="csharp" source="~/../code-windows/' + $docPath + '":::' + "`n`n"
59+
60+
# Replace our Sample Placeholder with references for docs
61+
$contents = $contents.Replace($sampleString, $snippet)
5462
}
5563
}
56-
57-
# Make any learn links relative
58-
$contents = $contents.Replace('https://learn.microsoft.com', '')
64+
}
5965

60-
$mdOutputPath = Join-Path $OutputDir $componentName
61-
62-
if (-not (Test-Path $mdOutputPath)) {
63-
New-Item -ItemType Directory -Path $mdOutputPath | Out-Null
64-
}
65-
66-
$markdownFileName = $markdownFile.Name
66+
# Make any learn links relative
67+
$contents = $contents.Replace('https://learn.microsoft.com', '')
68+
69+
$markdownFileName = $markdownFile.Name
70+
71+
# If the file is named the same as the component, rename it to index.md
72+
# This is so that the URL for the component is /componentName instead of /componentName/componentName
73+
if ($markdownFileName -eq "$componentName.md") {
74+
$markdownFileName = "index.md"
75+
}
76+
77+
$mdOutputPath = Join-Path $OutputDir $componentName
78+
$mdOutputFile = Join-Path $mdOutputPath $markdownFileName
79+
80+
# Create output directory if it doesn't exist
81+
if (-not (Test-Path $mdOutputPath)) {
82+
New-Item -ItemType Directory -Path $mdOutputPath | Out-Null
83+
}
84+
85+
# Write file contents
86+
Write-Host 'Writing File:', $mdOutputFile
87+
$contents | Set-Content $mdOutputFile
88+
89+
return $mdOutputFile
90+
}
6791

68-
# If the file is named the same as the component, rename it to index.md
69-
# This is so that the URL for the component is /componentName instead of /componentName/componentName
70-
if ($markdownFileName -eq "$componentName.md") {
71-
$markdownFileName = "index.md"
72-
}
92+
$componentsRoot = Resolve-Path $PSScriptRoot/../components/
7393

74-
$mdOutputFile = Join-Path $mdOutputPath $markdownFileName
94+
# For each component
95+
foreach ($componentFolder in Get-ChildItem -Path $componentsRoot -Directory) {
96+
$componentName = $componentFolder.Name
7597

76-
# Write file contents
77-
Write-Host 'Writing File:', $mdOutputFile
78-
$contents | Set-Content $mdOutputFile
98+
# Add component to TOC
99+
$markdownFiles = Get-ChildItem -Recurse -Path "$componentFolder/samples/**/*.md" | Where-Object { $_.FullName -notlike "*\bin\*" -and $_FullName -notlike "*\obj\*" }
79100

80-
# Add to TOC
81-
$mdOutputFile = $mdOutputFile.Trim('/') # need to remove initial / from path
82-
83-
# TOC is placed within output directory, hrefs are relative to TOC
84-
$tocHref = $mdOutputFile.Replace($OutputDir, '').Trim('\')
85-
$tocContents = $tocContents + " - name: $header`n href: $tocHref`n"
101+
# If there's only one markdown file, append it to the root of the TOC
102+
if ($markdownFiles.Count -eq 1) {
103+
$header = GetTitleFrontMatterFromMarkdownFile $markdownFiles[0]
104+
$mdOutputFile = ProcessMarkdownFile $markdownFiles[0]
105+
106+
$tocHref = $mdOutputFile.Trim('/').Replace($OutputDir, '').Trim('\')
107+
$tocContents += AppendTocItem $header 1 @{ "href" = $tocHref }
108+
}
109+
else {
110+
$tocContents += AppendTocItem $componentName 1 @{ "items" = "" }
111+
112+
# For each markdown file
113+
foreach ($markdownFile in $markdownFiles) {
114+
$header = GetTitleFrontMatterFromMarkdownFile $markdownFile
115+
$mdOutputFile = ProcessMarkdownFile $markdownFile
116+
117+
$tocHref = $mdOutputFile.Trim('/').Replace($OutputDir, '').Trim('\')
118+
$tocContents += AppendTocItem $header 2 @{ "href" = $tocHref }
119+
}
86120
}
87121
}
88122

0 commit comments

Comments
 (0)