---
title: "Dev Docs Generator"
description: "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
