mirror of
https://github.com/ChrisTitusTech/winutil.git
synced 2026-08-09 17:41:14 +10:00
Gave the docs steroids. sorry for the big pr. (#4892)
* Scaffold Astro + Starlight docs site
Bootstraps a new docs-astro project to replace the Hugo-based docs,
using Astro's Starlight framework with the content collection schema
and sidebar navigation configured for WinUtil's docs structure.
* Add WinUtil-branded Starlight theme
Restyles Starlight's default look with a dark-by-default grayscale
palette and WinUtil's brand blue (#0567ff, from the app logo) as the
single accent, Geist for UI text, and JetBrains Mono for code. Also
overrides the default theme provider so first-time visitors land on
dark mode instead of following OS preference.
* Add custom Hero and CornerCard components
Hero overrides Starlight's default hero with a full-bleed grid/glow
background, a browser-chrome-framed screenshot, and a badge row driven
by frontmatter data. CornerCard is a bordered feature card with corner
brackets, used for the landing page's feature grid.
* Migrate docs content from Hugo to Astro/Starlight
Ports the landing page, user guide sections, FAQ, known issues,
contributing guide, and a sample generated tweak reference page from
the Hugo site, converting Hugo shortcodes and GFM alert syntax to
their Starlight/MDX equivalents.
* Use Windows-style caption buttons in hero window chrome
Swap the macOS traffic-light dots for a minimize/maximize/close
button group, since WinUtil is a Windows tool.
* Use Windows-style caption glyph for terminal code blocks
Replace Expressive Code's default macOS dots on terminal-framed code
blocks with a right-aligned Windows minimize/maximize/close icon,
matching the hero window chrome.
* Archive the Hugo docs site as docs-old
* Promote Astro/Starlight docs from docs-astro to docs
* Show the launch command as a copyable code block on the docs homepage
* Add docs codeowner for seanh1995
* Register custom Header component for Starlight docs site
* Add custom navbar links to Astro docs, matching the old Hugo site's top nav
* Point dev docs generator at the Astro/Starlight docs site
Output moves from docs/content/dev (Hugo) to
docs/src/content/docs/code-reference (Astro/Starlight): .mdx instead
of .md, Starlight-style title="..." code fence labels instead of
Hugo's filename/linenos shortcode, and a ":::note" aside linking back
to each entry's source file. Frontmatter description is now pulled
from the JSON Description field. Also fixes a pre-existing bug where
the embedded JSON snippets were always missing their own closing
brace.
* Add seanh1995 as codeowner for the dev docs generator
* Wire up Code Reference section in docs sidebar
Adds an Architecture & Design page plus autogenerated Tweaks/Features
Reference groups pointing at docs/src/content/docs/code-reference, and
fixes the editLink base URL to the promoted docs/ path.
* Port architecture doc to code-reference and drop stale hyperv sample
Moves the Hugo-era architecture doc into
docs/src/content/docs/code-reference/architecture.mdx: drops the
Hugo-only weight/toc frontmatter, converts the embedded code fences to
Starlight's title="..." syntax, and repoints the "Related
Documentation" links at this site's actual slugs. Also removes the
hand-written reference/tweaks/hyperv.mdx placeholder now that the
generator produces the real page under code-reference/features.
* Keep pre-conversion backup of devdocs-generator.ps1
Snapshot of the script before it was pointed at the Astro/Starlight
docs site, for reference.
* updated workflow
* Update CODEOWNERS
* Hide edit-page link on the docs landing page
The splash-template landing page isn't a source doc meant to be edited
via GitHub like the rest of the guides, so skip showing the link.
* Add site footer with copyright line, matching the old Hugo docs
The Hugo site rendered "© {year} Chris Titus Tech. All rights
reserved." in its footer; Starlight's default footer had no
equivalent. Override it to append the same copyright line below the
existing edit-link/pagination row, and collapse that row entirely
when it has nothing in it (e.g. pages with editUrl disabled and no
prev/next) instead of leaving an empty gap.
* Fix vertical alignment and size of the arrow icon in hero/CTA buttons
The right-arrow icon read as floating above the button label's
baseline. Root cause was partly a genuine optical mismatch (fixed with
a small position nudge scoped to just the arrow icon, so it doesn't
also shift the unaffected GitHub icon) and partly the final CTA's copy
getting wrapped in a <p> by MDX's markdown parser, which behaved
slightly differently under the flex layout than the Hero component's
plain text node. Switching the CTA button's label to a JS string
expression avoids the wrapper and keeps both buttons' markup, and
rendering, identical.
* Use the dark fork-button screenshot in the contributing guide
Drop the unused light-mode variant and point the guide at
Fork-Button-Dark.png instead.
* Remove old Hugo docs site and pre-conversion backup files
The docs have moved to the Astro/Starlight site; the Hugo site
(docs-old/), its workflow backup, and the devdocs-generator.ps1
pre-conversion snapshot are no longer needed.
* keeping ai happy
* Bump sharp to 0.35.3 in docs site
This commit is contained in:
Sean (ANGRYxScotsman)
+48
-20
@@ -1,7 +1,7 @@
|
||||
<#
|
||||
.DESCRIPTION
|
||||
Generates Hugo markdown docs from config/tweaks.json and config/feature.json.
|
||||
Run by the GitHub Actions docs workflow before Hugo build.
|
||||
Generates Astro/Starlight markdown docs from config/tweaks.json and config/feature.json.
|
||||
Run by the GitHub Actions docs workflow before the Astro build.
|
||||
#>
|
||||
|
||||
function Update-Progress {
|
||||
@@ -81,12 +81,30 @@ function Get-RawJsonBlock {
|
||||
}
|
||||
}
|
||||
|
||||
# Include the item's own closing brace, stripped of the trailing comma that
|
||||
# only exists to separate it from the next sibling in the parent object.
|
||||
$closingLine = $JsonLines[$endIndex] -replace ',\s*$', ''
|
||||
|
||||
return @{
|
||||
LineNumber = $startIndex + 1
|
||||
RawText = ($JsonLines[$startIndex..$lastContentIndex] -join "`r`n")
|
||||
RawText = (($JsonLines[$startIndex..$lastContentIndex] + $closingLine) -join "`r`n")
|
||||
}
|
||||
}
|
||||
|
||||
function Get-GeneratedFromNote {
|
||||
# Builds the Starlight ":::note" aside pointing back at the source file for an entry.
|
||||
param (
|
||||
[Parameter(Mandatory)]
|
||||
[string]$SourceRelativePath
|
||||
)
|
||||
|
||||
$githubUrl = "https://github.com/ChrisTitusTech/winutil/blob/main/$SourceRelativePath"
|
||||
$note = ":::note`r`n"
|
||||
$note += "This page is generated from [``$SourceRelativePath``]($githubUrl). Edit the source file and regenerate the docs rather than editing this file directly.`r`n"
|
||||
$note += ":::`r`n`r`n"
|
||||
return $note
|
||||
}
|
||||
|
||||
function Get-ButtonFunctionMapping {
|
||||
# Parses Invoke-WPFButton.ps1 and returns a hashtable of button name -> function name.
|
||||
param (
|
||||
@@ -237,8 +255,8 @@ $repoRoot = Resolve-Path "$scriptDir/.."
|
||||
|
||||
$tweaksJsonPath = "$repoRoot/config/tweaks.json"
|
||||
$featuresJsonPath = "$repoRoot/config/feature.json"
|
||||
$tweaksOutputDir = "$repoRoot/docs/content/dev/tweaks"
|
||||
$featuresOutputDir = "$repoRoot/docs/content/dev/features"
|
||||
$tweaksOutputDir = "$repoRoot/docs/src/content/docs/code-reference/tweaks"
|
||||
$featuresOutputDir = "$repoRoot/docs/src/content/docs/code-reference/features"
|
||||
$publicFunctionsDir = "$repoRoot/functions/public"
|
||||
$privateFunctionsDir = "$repoRoot/functions/private"
|
||||
|
||||
@@ -282,21 +300,25 @@ Update-Progress "Building button-to-function mapping" 30
|
||||
$buttonFunctionMap = Get-ButtonFunctionMapping -ButtonFilePath "$publicFunctionsDir/Invoke-WPFButton.ps1"
|
||||
|
||||
Update-Progress "Updating documentation links in JSON" 40
|
||||
Add-LinkAttributeToJson -JsonFilePath $tweaksJsonPath -UrlPrefix "$baseUrl/dev/tweaks" -ItemNameToCut $itemnametocut
|
||||
Add-LinkAttributeToJson -JsonFilePath $featuresJsonPath -UrlPrefix "$baseUrl/dev/features" -ItemNameToCut $itemnametocut
|
||||
Add-LinkAttributeToJson -JsonFilePath $tweaksJsonPath -UrlPrefix "$baseUrl/code-reference/tweaks" -ItemNameToCut $itemnametocut
|
||||
Add-LinkAttributeToJson -JsonFilePath $featuresJsonPath -UrlPrefix "$baseUrl/code-reference/features" -ItemNameToCut $itemnametocut
|
||||
|
||||
# Reload lines after link update so line numbers in docs are accurate
|
||||
$tweaksLines = Get-Content -Path $tweaksJsonPath
|
||||
$featuresLines = Get-Content -Path $featuresJsonPath
|
||||
|
||||
# ==============================================================================
|
||||
# Clean up old generated .md files (preserve _index.md)
|
||||
# Clean up old generated .mdx files
|
||||
# ==============================================================================
|
||||
|
||||
Update-Progress "Cleaning up old generated docs" 45
|
||||
foreach ($dir in @($tweaksOutputDir, $featuresOutputDir)) {
|
||||
Get-ChildItem -Path $dir -Recurse -Filter *.md | Where-Object {
|
||||
$_.Name -ne "_index.md"
|
||||
if (-Not (Test-Path -Path $dir)) { continue }
|
||||
Get-ChildItem -Path $dir -Recurse -Filter *.mdx | Where-Object {
|
||||
# No category index.mdx pages exist yet. If one is added later as a
|
||||
# category landing page, uncomment this line to keep it from being wiped.
|
||||
# $_.Name -ne "index.mdx"
|
||||
$true
|
||||
} | Remove-Item -Force
|
||||
}
|
||||
|
||||
@@ -319,25 +341,28 @@ foreach ($itemName in $tweakNames) {
|
||||
$category = $item.category -replace '[^a-zA-Z0-9]', '-'
|
||||
$displayName = $itemName -replace $itemnametocut, ''
|
||||
$categoryDir = "$tweaksOutputDir/$category"
|
||||
$filename = "$categoryDir/$displayName.md"
|
||||
$filename = "$categoryDir/$displayName.mdx"
|
||||
|
||||
if (-Not (Test-Path -Path $categoryDir)) { New-Item -ItemType Directory -Path $categoryDir | Out-Null }
|
||||
|
||||
$title = $item.Content -replace '"', '\"'
|
||||
$content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n`r`n"
|
||||
$title = $item.Content -replace '"', '\"'
|
||||
$description = if ($item.Description) { $item.Description -replace '"', '\"' } else { '' }
|
||||
$content = "---`r`ntitle: `"$title`"`r`ndescription: `"$description`"`r`n---`r`n`r`n"
|
||||
|
||||
if ($item.Type -eq "Button") {
|
||||
$funcName = $buttonFunctionMap[$itemName]
|
||||
if ($funcName -and $functionFiles.ContainsKey($funcName)) {
|
||||
$func = $functionFiles[$funcName]
|
||||
$content += "``````powershell {filename=`"$($func.RelativePath)`",linenos=inline,linenostart=1}`r`n"
|
||||
$content += Get-GeneratedFromNote -SourceRelativePath $func.RelativePath
|
||||
$content += "``````powershell title=`"$($func.RelativePath)`"`r`n"
|
||||
$content += $func.Content + "`r`n"
|
||||
$content += "```````r`n"
|
||||
}
|
||||
} else {
|
||||
$jsonBlock = Get-RawJsonBlock -ItemName $itemName -JsonLines $tweaksLines
|
||||
if ($jsonBlock) {
|
||||
$content += "``````json {filename=`"config/tweaks.json`",linenos=inline,linenostart=$($jsonBlock.LineNumber)}`r`n"
|
||||
$content += Get-GeneratedFromNote -SourceRelativePath "config/tweaks.json"
|
||||
$content += "``````json title=`"config/tweaks.json`"`r`n"
|
||||
$content += $jsonBlock.RawText + "`r`n"
|
||||
$content += "```````r`n"
|
||||
}
|
||||
@@ -375,25 +400,28 @@ foreach ($itemName in $featureNames) {
|
||||
$category = $item.category -replace '[^a-zA-Z0-9]', '-'
|
||||
$displayName = $itemName -replace $itemnametocut, ''
|
||||
$categoryDir = "$featuresOutputDir/$category"
|
||||
$filename = "$categoryDir/$displayName.md"
|
||||
$filename = "$categoryDir/$displayName.mdx"
|
||||
|
||||
if (-Not (Test-Path -Path $categoryDir)) { New-Item -ItemType Directory -Path $categoryDir | Out-Null }
|
||||
|
||||
$title = $item.Content -replace '"', '\"'
|
||||
$content = "---`r`ntitle: `"$title`"`r`ndescription: `"`"`r`n---`r`n`r`n"
|
||||
$title = $item.Content -replace '"', '\"'
|
||||
$description = if ($item.Description) { $item.Description -replace '"', '\"' } else { '' }
|
||||
$content = "---`r`ntitle: `"$title`"`r`ndescription: `"$description`"`r`n---`r`n`r`n"
|
||||
|
||||
if ($item.category -in $functionEmbedCategories) {
|
||||
$funcName = if ($item.function) { $item.function } else { $buttonFunctionMap[$itemName] }
|
||||
if ($funcName -and $functionFiles.ContainsKey($funcName)) {
|
||||
$func = $functionFiles[$funcName]
|
||||
$content += "``````powershell {filename=`"$($func.RelativePath)`",linenos=inline,linenostart=1}`r`n"
|
||||
$content += Get-GeneratedFromNote -SourceRelativePath $func.RelativePath
|
||||
$content += "``````powershell title=`"$($func.RelativePath)`"`r`n"
|
||||
$content += $func.Content + "`r`n"
|
||||
$content += "```````r`n"
|
||||
}
|
||||
} else {
|
||||
$jsonBlock = Get-RawJsonBlock -ItemName $itemName -JsonLines $featuresLines
|
||||
if ($jsonBlock) {
|
||||
$content += "``````json {filename=`"config/feature.json`",linenos=inline,linenostart=$($jsonBlock.LineNumber)}`r`n"
|
||||
$content += Get-GeneratedFromNote -SourceRelativePath "config/feature.json"
|
||||
$content += "``````json title=`"config/feature.json`"`r`n"
|
||||
$content += $jsonBlock.RawText + "`r`n"
|
||||
$content += "```````r`n"
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user