winutil/tools/devdocs-generator.md

title, description

title	description
Dev Docs Generator	How the devdocs-generator.ps1 script works

Dev Docs Generator

The devdocs-generator.ps1 script automatically generates Hugo-compatible markdown files for the development documentation. It pulls content directly from the JSON config files and PowerShell function files so the docs never go out of sync.

When Does It Run?

• Automatically in CI via the GitHub Actions docs.yaml workflow before Hugo builds the site
• Triggered when any of these change: docs/**, config/tweaks.json, config/feature.json, functions/**
• Can also be run manually with workflow_dispatch

What Does It Do?

1. Loads the Data

• Reads config/tweaks.json and config/feature.json
• Reads all .ps1 function files from functions/public/ and functions/private/
• Parses Invoke-WPFButton.ps1 to build a mapping of button names to their function names

2. Updates Links in JSON

• Adds or updates a "link" property on every entry in both JSON config files
• Each link points to that entry's documentation page on the Hugo site

3. Cleans Up Old Docs

• Deletes all .md files (except _index.md) from docs/content/dev/tweaks/ and docs/content/dev/features/
• This prevents duplicate or orphaned files from previous runs

4. Generates Tweak Documentation

For each entry in tweaks.json that belongs to a documented category:

• Button type entries get the mapped PowerShell function file embedded
• All other types get the raw JSON snippet embedded with correct line numbers from the source file
• Entries with registry changes get a Registry Changes section added
• Entries with services get the Set-WinUtilService.ps1 function appended

5. Generates Feature Documentation

For each entry in feature.json that belongs to a documented category:

• Fixes and Legacy Windows Panels get the mapped PowerShell function file embedded
• Features get the raw JSON snippet embedded with correct line numbers

6. Output Format

• Every .md file gets Hugo frontmatter with title and description
• Code blocks use Hugo syntax with filename labels and line numbers
• Files are organized into category subdirectories matching the JSON category field

Documented Categories

The script generates docs for entries in these categories:

• Essential Tweaks
• z__Advanced Tweaks - CAUTION
• Customize Preferences
• Performance Plans
• Features
• Fixes
• Legacy Windows Panels

File Structure

docs/content/dev/
  tweaks/
    Essential-Tweaks/
    z--Advanced-Tweaks---CAUTION/
    Customize-Preferences/
    Performance-Plans/
  features/
    Features/
    Fixes/
    Legacy-Windows-Panels/

How File Names Are Derived

The script strips common prefixes from the JSON key names using the pattern WPF(WinUtil|Toggle|Features?|Tweaks?|Panel|Fix(es)?)?. For example:

JSON Key	Generated File
WPFTweaksHiber	Hiber.md
WPFTweaksDeBloat	DeBloat.md
WPFFeatureshyperv	hyperv.md
WPFPanelDISM	DISM.md

Key Points

• The JSON config files are the single source of truth
• Manual edits to generated .md files will be overwritten on the next run
• The script does not touch _index.md files or architecture.md
• Category directories are created automatically if they don't exist
• The "link" property added to JSON entries is excluded from the displayed code blocks