`).
-- Some packages installed by Winutil (AppX/MSIX) include removal helpers; check the app entry or use Winutil's remove helpers when available.
+- Some packages installed by WinUtil (AppX/MSIX) include removal helpers; check the app entry or use WinUtil's remove helpers when available.
### Will installed apps auto-update?
-Applications with built-in update mechanisms will auto-update. You can also update them via WinGet/Chocolatey commands or through Winutil's "Upgrade Selected" feature.
-## Updates & Maintenance
+Applications with built-in update mechanisms will auto-update. You can also update them via WinGet/Chocolatey commands or through WinUtil's "Upgrade Selected" feature.
+
+## Updates & maintenance
### Should I disable Windows Updates?
+
Generally, **no**. Security updates are important. However, you might:
+
- Use "Security Updates Only" to avoid feature updates
- Pause updates temporarily for stability
- Disable only during critical work periods
### How do I re-enable updates after disabling them?
-1. Open Winutil
+
+1. Open WinUtil
2. Go to the **Updates** tab
3. Click **Default Updates**
4. Updates will resume normally
### What's the difference between "Security Updates Only" and "Disable Updates"?
+
- **Security Updates Only**: Installs critical security patches, blocks feature updates (major versions)
- **Disable Updates**: Blocks ALL updates including security (not recommended)
## Troubleshooting
-### Winutil won't open after running the command
+### WinUtil won't open after running the command
+
Possible causes:
+
1. **Antivirus blocking**: Add PowerShell exception
2. **Not run as Admin**: Restart PowerShell as Administrator
3. **Corrupted download**: Close PowerShell, reopen, try again
4. **Windows Defender**: Allow the script
-### My antivirus flags Winutil as malicious
-This is a false positive. Winutil makes system changes that antivirus programs may flag. The code is open source and audited. Add an exception if needed.
+### My antivirus flags WinUtil as malicious
+
+This is a false positive. WinUtil makes system changes that antivirus programs may flag. The code is open source and audited. Add an exception if needed.
### An application failed to install
+
Troubleshooting steps:
+
1. Check your internet connection
2. Try installing just that one application
3. Review error messages in the output panel
@@ -169,40 +205,50 @@ Troubleshooting steps:
5. Try the WinGet Reinstall fix
### Network tweaks broke my internet connection
-1. Open Winutil
+
+1. Open WinUtil
2. Go to **Config** > **Fixes**
3. Click **Reset Network**
4. Restart your computer
5. Connection should be restored
### I can't access certain Windows features after applying tweaks
+
Undo the tweaks that might have affected those features:
-1. Reopen Winutil
+
+1. Reopen WinUtil
2. Select the tweaks you applied
3. Click **Undo Selected Tweaks**
If that doesn't work, use System Restore to revert to a previous state.
-## Advanced Topics
+## Advanced topics
-### Can I run Winutil on Windows Server?
-Yes, Winutil works on Windows Server editions, though some features may not be applicable or may behave differently.
+### Can I run WinUtil on Windows Server?
-### Does Winutil work with Windows LTSC?
-Yes, Winutil works with Windows 10/11 LTSC editions. Some applications may not be available depending on your configuration.
+Yes, WinUtil works on Windows Server editions, though some features may not be applicable or may behave differently.
+
+### Does WinUtil work with Windows LTSC?
+
+Yes, WinUtil works with Windows 10/11 LTSC editions. Some applications may not be available depending on your configuration.
+
+### Can I use WinUtil in a corporate/enterprise environment?
-### Can I use Winutil in a corporate/enterprise environment?
Yes, but check your organization's policies first. Some tweaks may conflict with Group Policy or other corporate requirements.
-### How do I automate Winutil for multiple PCs?
-See the [Automation Guide](/userguide/automation/) for details on:
+### How do I automate WinUtil for multiple PCs?
+
+See the [Automation Guide](/guides/automation/) for details on:
+
- Configuration files
- PowerShell parameters
- Batch deployment
- Silent installation
-### Can I contribute to Winutil?
+### Can I contribute to WinUtil?
+
Yes! Contributions are welcome:
+
- Report bugs on GitHub Issues
- Submit pull requests for fixes/features
- Improve documentation
@@ -210,13 +256,16 @@ Yes! Contributions are welcome:
See the [Contributing Guide](/contributing/) for details.
-## Privacy & Security
+## Privacy & security
-### Does Winutil collect any data?
-No, Winutil itself doesn't collect or transmit any user data. It's a local PowerShell script.
+### Does WinUtil collect any data?
+
+No, WinUtil itself doesn't collect or transmit any user data. It's a local PowerShell script.
### What telemetry does the Disable Telemetry tweak block?
+
It disables:
+
- Windows diagnostic data collection
- Activity history tracking
- Feedback requests
@@ -224,12 +273,15 @@ It disables:
- Error reporting (optional)
### Will removing Microsoft Store affect security updates?
+
No, Windows security updates are independent of the Microsoft Store.
## Performance
-### Will Winutil make my PC faster?
+### Will WinUtil make my PC faster?
+
Tweaks can improve performance by:
+
- Reducing background processes
- Disabling unnecessary services
- Cleaning temporary files
@@ -238,29 +290,32 @@ Tweaks can improve performance by:
Results may vary depending on your system.
### What's the best preset for gaming?
+
Use the **Desktop** preset, then additionally apply:
+
- Disable GameDVR
- Ultimate Performance power plan
- Disable full-screen optimizations (Advanced)
- Set display for performance (Advanced)
-### How much RAM does Winutil use?
-Winutil itself uses about 50-100 MB while running. Once closed, it is removed from memory.
+### How much RAM does WinUtil use?
-## Error Messages
+WinUtil itself uses about 50-100 MB while running. Once closed, it is removed from memory.
+
+## Error messages
### "Access Denied" errors
+
- Ensure PowerShell is running as Administrator
- Check if the antivirus is blocking changes
- Verify you have ownership of files/registry keys
-
-## Still Need Help?
+## Still need help?
Can't find your answer? Try these resources:
-- **[Known Issues](/knownissues/)** - Check if it's a known problem
-- **[User Guide](/userguide/)** - Comprehensive documentation
-- **[Discord Community](https://discord.gg/RUbZUZyByQ)** - Get help from other users
-- **[GitHub Issues](https://github.com/ChrisTitusTech/winutil/issues)** - Report bugs
-- **[YouTube Tutorial](https://www.youtube.com/watch?v=6UQZ5oQg8XA)** - Video walkthrough
+- **[Known Issues](/known-issues/)** β Check if it's a known problem
+- **[User Guide](/guides/getting-started/)** β Comprehensive documentation
+- **[Discord Community](https://discord.gg/RUbZUZyByQ)** β Get help from other users
+- **[GitHub Issues](https://github.com/ChrisTitusTech/winutil/issues)** β Report bugs
+- **[YouTube Tutorial](https://www.youtube.com/watch?v=6UQZ5oQg8XA)** β Video walkthrough
diff --git a/docs/src/content/docs/guides/application.mdx b/docs/src/content/docs/guides/application.mdx
new file mode 100644
index 00000000..58a78196
--- /dev/null
+++ b/docs/src/content/docs/guides/application.mdx
@@ -0,0 +1,57 @@
+---
+title: Applications
+description: Use the Applications tab in WinUtil to install, upgrade, uninstall, and review supported apps.
+sidebar:
+ order: 2
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Use the Applications tab to install, upgrade, uninstall, and review supported apps from one place. WinUtil relies on package manager support for these actions, so the available results depend on what WinGet can detect and manage on your system.
+
+
+
+* Choose the applications you want to install or upgrade.
+ * For programs not currently installed, this action will install them.
+ * For programs already installed, this action will update them to the latest version.
+* Click the `Install/Upgrade Selected` button to start the installation or upgrade process.
+
+
+
+
+* Simply press the `Upgrade All` button.
+* This upgrades every supported installed program without individual selection.
+
+
+
+
+* Select the programs you wish to uninstall.
+* Click the `Uninstall Selected` button to remove them.
+
+
+
+
+* Click the `Show Installed Apps` button.
+* This scans for and selects installed applications supported by WinGet.
+
+
+
+
+* Click the `Clear Selection` button.
+* This clears all current selections.
+
+
+
+
+
+:::tip
+If you have trouble finding an application, press `Ctrl + F` and search for its name. The list filters as you type.
+:::
+
+:::note
+`Show Installed Apps` only selects software that WinGet can identify. Apps installed outside supported package sources may not appear.
+:::
+
+:::caution
+Before uninstalling or upgrading apps, close any running programs first. Some packages may still prompt for input or fail if their source is unavailable.
+:::
diff --git a/docs/content/userguide/automation/_index.md b/docs/src/content/docs/guides/automation.mdx
similarity index 80%
rename from docs/content/userguide/automation/_index.md
rename to docs/src/content/docs/guides/automation.mdx
index 61c22ecc..f44efae9 100644
--- a/docs/content/userguide/automation/_index.md
+++ b/docs/src/content/docs/guides/automation.mdx
@@ -1,8 +1,8 @@
---
title: Automation
-weight: 7
-prev: /userguide/updates/
-next: /userguide/win11creator/
+description: Run WinUtil from an exported configuration file or a preset to automate setups across multiple PCs.
+sidebar:
+ order: 6
---
Use Automation to run WinUtil from an exported configuration file.
@@ -40,5 +40,6 @@ This is useful for:
- Reusing a known-good baseline after reinstalling Windows
- Standardizing deployments for labs, workstations, or personal setups
-> [!NOTE]
-> Run the command in an elevated PowerShell session so WinUtil can apply system-level changes.
+:::note
+Run the command in an elevated PowerShell session so WinUtil can apply system-level changes.
+:::
diff --git a/docs/content/userguide/features/_index.md b/docs/src/content/docs/guides/features.mdx
similarity index 87%
rename from docs/content/userguide/features/_index.md
rename to docs/src/content/docs/guides/features.mdx
index 0c4e3e5d..ca5a76b8 100644
--- a/docs/content/userguide/features/_index.md
+++ b/docs/src/content/docs/guides/features.mdx
@@ -1,15 +1,15 @@
---
title: Features
-weight: 5
-prev: /userguide/tweaks/
-next: /userguide/updates/
+description: Install optional Windows components and run common repair tasks from the Features and Fixes sections.
+sidebar:
+ order: 4
---
Use the **Features** and **Fixes** sections to install optional Windows components and run common repair tasks.
This page maps to the **Config** tab in WinUtil. Some actions complete immediately, while others may prompt, download files from Microsoft, or require a restart before the change is fully available.
-{{< image src="images/config-tab-new" alt="Config tab with features and fixes" >}}
+
## Windows Features
diff --git a/docs/src/content/docs/guides/getting-started.mdx b/docs/src/content/docs/guides/getting-started.mdx
new file mode 100644
index 00000000..dcffba8f
--- /dev/null
+++ b/docs/src/content/docs/guides/getting-started.mdx
@@ -0,0 +1,259 @@
+---
+title: Getting Started
+description: The safest way to get started with WinUtil and the first actions most users take.
+sidebar:
+ order: 1
+---
+
+## Welcome to WinUtil!
+
+WinUtil helps you install apps, apply system tweaks, run common fixes, and manage Windows settings from one place. This guide covers the safest way to get started and the first actions most users take.
+
+## System requirements
+
+Before running WinUtil, ensure your system meets these requirements:
+
+:::caution
+Windows 10 is not supported by WinUtil. Windows 10 reached the end of support on **October 14, 2025**.
+:::
+
+- **Operating system**: Windows 11
+- **PowerShell**: Version 5.1 or later (included by default in Windows 11)
+- **Administrator access**: Required for system-level changes
+- **Internet connection**: Required for downloading applications and updates
+- **.NET Framework**: Version 4.5 or later (usually pre-installed)
+
+## Installation
+
+WinUtil doesn't require traditional installation. It runs directly from PowerShell as a script.
+
+### Step 1: Open PowerShell as Administrator
+
+There are several ways to open PowerShell with admin rights:
+
+**Method 1: Start menu (recommended)**
+
+1. Right-click the Windows Start button.
+2. Select "Terminal (Admin)".
+
+**Method 2: Search method**
+
+1. Press the `Windows` key.
+2. Type "PowerShell" or "Terminal".
+3. Press `Ctrl + Shift + Enter` to launch as administrator.
+4. Or right-click and select "Run as administrator".
+
+**Method 3: Run dialog**
+
+1. Press `Windows + R`.
+2. Type `powershell`.
+3. Press `Ctrl + Shift + Enter`.
+
+### Step 2: Run the launch command
+
+With PowerShell running as Administrator, run one of the following commands depending on the release channel you want.
+
+**Stable release (recommended)**
+
+```powershell
+irm "https://christitus.com/win" | iex
+```
+
+**Development branch (bleeding edge β for testing only)**
+
+```powershell
+irm "https://christitus.com/windev" | iex
+```
+
+:::note
+- The `irm` command downloads the script, and `iex` executes it. This is safe when downloading from the official source.
+- The development branch may contain experimental changes and should only be used for testing on non-production systems.
+:::
+
+### Step 3: Wait for WinUtil to load
+
+The first time you run WinUtil, it may take a few moments to:
+
+- Download the latest version
+- Initialize the interface
+- Load all features and settings
+
+## First time setup
+
+### Understanding the interface
+
+WinUtil opens with a clean, tabbed interface:
+
+**Main tabs**:
+
+- **Install**: Browse and install applications
+- **Tweaks**: Apply system optimizations and customizations
+- **Config**: Access system tools and utilities
+- **Updates**: Manage Windows updates
+- **Win11 Creator**: Build a customized Windows 11 ISO from an official Microsoft image
+
+## Your first actions
+
+Here are some recommended first steps for new users:
+
+### 1. Create a restore point
+
+Before making any changes, create a system restore point:
+
+1. Go to the **Tweaks** tab.
+2. Find "Create Restore Point" under Essential Tweaks.
+3. Check the box and click **Run Tweaks**.
+
+This gives you a rollback point if needed.
+
+### 2. Install essential applications
+
+1. Navigate to the **Install** tab.
+2. Browse categories or use the search bar.
+3. Check the applications you want to install.
+4. Click "Install/Upgrade Selected" at the bottom.
+
+### 3. Apply basic tweaks
+
+For a better Windows experience with minimal risk:
+
+1. Go to the **Tweaks** tab.
+2. Select the **Standard** preset for a balanced configuration.
+3. Review the selected tweaks.
+4. Click **Run Tweaks**.
+
+:::note
+Some tweaks, fixes, and update changes may require a restart or sign-out before the full effect is visible.
+:::
+
+## Common tasks
+
+### Installing applications
+
+**Single application**:
+
+1. Open the **Install** tab.
+2. Search for the application name.
+3. Check the box next to it.
+4. Click "Install/Upgrade Selected".
+
+**Multiple applications**:
+
+1. Check multiple application boxes.
+2. All checked apps will install in sequence.
+3. Install and uninstall progress is shown in the window-level bottom panel, including the current package or package-manager batch and overall completion.
+
+### Applying tweaks
+
+**Essential tweaks** (safe for all users):
+
+1. Go to the **Tweaks** tab.
+2. Select from the Essential Tweaks section.
+3. Click **Run Tweaks**.
+
+**Advanced tweaks** (use with caution):
+
+1. Only modify if you understand the implications.
+2. Always create a restore point first.
+3. Review documentation for each tweak.
+
+**Undoing tweaks**:
+
+1. Select the same tweaks you applied.
+2. Click **Undo Selected Tweaks**.
+3. The system reverts to the previous state.
+
+### Using quick fixes
+
+For common Windows issues:
+
+1. Go to the **Config** tab.
+2. Navigate to the **Fixes** section.
+3. Select the appropriate fix:
+ - **Reset Network**: Fixes network connectivity issues
+ - **Reset Windows Update**: Resolves update problems
+ - **System Corruption Scan**: Repairs corrupted system files
+ - **WinGet Reinstall**: Fixes package manager issues
+
+### Changing DNS servers
+
+For improved privacy and speed:
+
+1. Go to the **Tweaks** tab.
+2. Find the DNS section.
+3. Select a provider:
+ - **Cloudflare**: Fast and privacy-focused
+ - **Google**: Reliable and widely used
+ - **Quad9**: Security-focused with malware blocking
+ - **AdGuard**: Blocks ads and trackers
+4. Click **Apply**.
+
+## Understanding presets
+
+WinUtil offers several preset configurations:
+
+- **Minimal**: Minimal changes that keep most Windows features
+- **Standard**: A good middle ground for most users
+- **Advanced**: Selects a focused set of safer advanced tweaks
+
+## Safety tips
+
+β
**Do**:
+
+- Create restore points before major changes
+- Read tweak descriptions before applying
+- Start with Essential Tweaks
+- Keep Windows up to date
+- Back up important data
+
+β **Don't**:
+
+- Apply all tweaks at once without understanding them
+- Skip creating restore points
+- Use Advanced Tweaks without research
+- Disable security features unless necessary
+- Run on production systems without testing
+
+## Troubleshooting first run
+
+### Script won't download
+
+If the launch command fails:
+
+- Make sure PowerShell or Terminal is running as Administrator.
+- Confirm the PC has internet access and can reach `christitus.com`.
+- Retry from a normal PowerShell session rather than a restricted enterprise shell profile.
+- If the command starts and then closes immediately, reopen Terminal as Administrator and run it again so you can read the error output.
+
+If it still fails, check the [Known Issues](/known-issues/) page.
+
+## Next steps
+
+Now that you're set up, explore these guides:
+
+- [Applications Guide](/guides/application/) β Learn about installing, upgrading, and uninstalling software
+- [Tweaks Guide](/guides/tweaks/) β Understand system optimizations
+- [FAQ](/faq/) β Common questions and answers
+
+## Getting help
+
+If you need assistance:
+
+- **Documentation**: Browse this documentation site
+- **Known Issues**: Check the [Known Issues](/known-issues/) page
+- **Discord**: Join the [community Discord server](https://discord.gg/RUbZUZyByQ)
+- **GitHub Issues**: Report bugs on [GitHub](https://github.com/ChrisTitusTech/winutil/issues)
+- **YouTube**: Watch [video tutorials](https://www.youtube.com/watch?v=6UQZ5oQg8XA)
+
+## Quick reference card
+
+| Task | Location | Action |
+| ---- | -------- | ------ |
+| Install or upgrade apps | Install tab | Check boxes β Install/Upgrade Selected |
+| Uninstall apps | Install tab | Check boxes β Uninstall Selected |
+| Apply tweaks | Tweaks tab | Select tweaks β Run Tweaks |
+| Undo tweaks | Tweaks tab | Select tweaks β Undo Selected Tweaks |
+| Create restore point | Tweaks tab | Essential Tweaks section |
+| Fix network | Config tab | Fixes β Reset Network |
+| Change DNS | Tweaks tab | DNS section |
+| Open Control Panel | Config tab | Legacy Windows Panels |
diff --git a/docs/content/userguide/_index.md b/docs/src/content/docs/guides/index.mdx
similarity index 68%
rename from docs/content/userguide/_index.md
rename to docs/src/content/docs/guides/index.mdx
index ba92676e..bb64f4b7 100644
--- a/docs/content/userguide/_index.md
+++ b/docs/src/content/docs/guides/index.mdx
@@ -1,18 +1,15 @@
---
title: User Guide
-weight: 2
-breadcrumbs: false
-cascade:
- type: docs
- params:
- reversePagination: false
- breadcrumbs: false
+description: Overview of the WinUtil User Guide β installing apps, applying tweaks, running fixes, and managing updates.
+sidebar:
+ order: 0
---
Welcome to the official User Guide for **Winutil**, your all-in-one Windows toolkit.
-> [!IMPORTANT]
-> Windows 10 is not supported by Winutil. Windows 10 reached the end of support on **October 14, 2025**.
+:::caution
+Windows 10 is not supported by Winutil. Windows 10 reached the end of support on **October 14, 2025**.
+:::
## What is Winutil?
@@ -39,13 +36,13 @@ Winutil is designed for:
New to Winutil? Follow the guides below in order to get up and running quickly:
-1. **[Getting Started](getting-started/)** - Learn how to launch Winutil and understand the basics.
-2. **[Applications](application/)** - Install, update, and remove apps with ease.
-3. **[Tweaks](tweaks/)** - Apply performance, privacy, and usability improvements.
-4. **[Features](features/)** - Explore built-in tools and common Windows fixes.
-5. **[Updates](updates/)** - Configure how Windows Update behaves on your system.
-6. **[Automation](automation/)** - Automate setups and reuse configurations across PCs.
-7. **[Win11 Creator](win11creator/)** - Build a custom debloated Windows 11 ISO.
+1. **[Getting Started](/guides/getting-started/)** - Learn how to launch Winutil and understand the basics.
+2. **[Applications](/guides/application/)** - Install, update, and remove apps with ease.
+3. **[Tweaks](/guides/tweaks/)** - Apply performance, privacy, and usability improvements.
+4. **[Features](/guides/features/)** - Explore built-in tools and common Windows fixes.
+5. **[Updates](/guides/updates/)** - Configure how Windows Update behaves on your system.
+6. **[Automation](/guides/automation/)** - Automate setups and reuse configurations across PCs.
+7. **[Win11 Creator](/guides/win11creator/)** - Build a custom debloated Windows 11 ISO.
## Main Features
@@ -53,13 +50,13 @@ New to Winutil? Follow the guides below in order to get up and running quickly:
Browse and install hundreds of popular applications with a single click. No more hunting for download links or dealing with installer bloat.
-**[Read the Applications Guide β](application/)**
+**[Read the Applications Guide β](/guides/application/)**
### System Tweaks
Apply optimizations for performance, privacy, and usability. Choose from preset configurations or customize individual tweaks.
-**[Read the Tweaks Guide β](tweaks/)**
+**[Read the Tweaks Guide β](/guides/tweaks/)**
### Config & Fixes
@@ -69,7 +66,7 @@ Quick fixes for common Windows problems:
- Repair system files
- Access legacy Windows panels
-**[Read the Features Guide β](features/)**
+**[Read the Features Guide β](/guides/features/)**
### Update Management
@@ -79,7 +76,7 @@ Take control of Windows Updates with options to:
- Pause updates
- Manage driver updates
-**[Read the Updates Guide β](updates/)**
+**[Read the Updates Guide β](/guides/updates/)**
### Automation
@@ -89,13 +86,13 @@ Automate Winutil configurations for:
- Consistent configurations
- Scripted installations
-**[Read the Automation Guide β](automation/)**
+**[Read the Automation Guide β](/guides/automation/)**
### Windows 11 Creator
Build a custom Windows 11 ISO with bloatware removed, telemetry disabled, and hardware requirement checks bypassed. You can then export it as an ISO file or write it directly to a USB drive.
-**[Read the Win11 Creator Guide β](win11creator/)**
+**[Read the Win11 Creator Guide β](/guides/win11creator/)**
## Safety and Best Practices
@@ -127,8 +124,8 @@ Before using Winutil:
Need help?
- **Documentation**: You're reading it. Use the navigation menu.
-- **FAQ**: Check [Frequently Asked Questions](../faq/)
-- **Known Issues**: Review [Known Issues](../knownissues/)
+- **FAQ**: Check [Frequently Asked Questions](/faq/)
+- **Known Issues**: Review [Known Issues](/known-issues/)
- **Discord**: Join the [community Discord](https://discord.gg/RUbZUZyByQ)
- **GitHub**: Report bugs on [GitHub Issues](https://github.com/ChrisTitusTech/winutil/issues)
- **YouTube**: Watch [video tutorials](https://www.youtube.com/watch?v=6UQZ5oQg8XA)
@@ -143,20 +140,16 @@ Want to help improve Winutil?
- **Improve Docs**: Help expand this documentation
- **Share Knowledge**: Help others in Discord
-**[Read Contributing Guide β](../contributing/)**
+**[Read Contributing Guide β](/contributing/)**
## Video Tutorial
-Watch the complete WinUtil overview:
+Watch the complete WinUtil overview: [https://www.youtube.com/watch?v=6UQZ5oQg8XA](https://www.youtube.com/watch?v=6UQZ5oQg8XA)
-{{< youtube id=6UQZ5oQg8XA loading=lazy >}}
-
-Ready to get started? Head to the **[Getting Started Guide](getting-started/)**.
+Ready to get started? Head to the **[Getting Started Guide](/guides/getting-started/)**.
## Next
Dive right into the following section to get started:
-{{< cards >}}
- {{< card link="getting-started" title="Getting Started" icon="document-text" subtitle="Learn how to use WinUtil." >}}
-{{< /cards >}}
+**[Getting Started](/guides/getting-started/)** β Learn how to use WinUtil.
diff --git a/docs/content/userguide/tweaks/_index.md b/docs/src/content/docs/guides/tweaks.mdx
similarity index 89%
rename from docs/content/userguide/tweaks/_index.md
rename to docs/src/content/docs/guides/tweaks.mdx
index ef16108b..cd3af0b5 100644
--- a/docs/content/userguide/tweaks/_index.md
+++ b/docs/src/content/docs/guides/tweaks.mdx
@@ -1,11 +1,11 @@
---
title: Tweaks
-weight: 4
-prev: /userguide/application/
-next: /userguide/features/
+description: Apply recommended Windows changes, review optional presets, and adjust supporting settings such as DNS and power plans.
+sidebar:
+ order: 3
---
-{{< image src="images/tweaks-tab-new" alt="Image of Tweaks Tab" >}}
+
Use the Tweaks tab to apply recommended Windows changes, review optional presets, and adjust a few supporting settings such as DNS and power plans. Start with a preset unless you already know which individual tweaks you want.
@@ -23,11 +23,13 @@ Use the quick-selection buttons at the top of the Tweaks tab to speed up setup:
* **Select Tweaks**: Choose the tweaks you want to apply. You can use the presets available at the top for convenience.
* **Run Tweaks**: After selecting the desired tweaks, click **Run Tweaks** at the bottom of the screen.
-> [!NOTE]
-> To see what each preset includes, view [preset.json](https://github.com/ChrisTitusTech/winutil/blob/main/config/preset.json).
+:::note
+To see what each preset includes, view [preset.json](https://github.com/ChrisTitusTech/winutil/blob/main/config/preset.json).
+:::
-> [!IMPORTANT]
-> Some tweaks take effect immediately, while others may require Explorer to restart, a sign-out, or a full reboot.
+:::caution
+Some tweaks take effect immediately, while others may require Explorer to restart, a sign-out, or a full reboot.
+:::
### Undo Tweaks
* **Open the Tweaks tab**: Go to the **Tweaks** tab located next to **Install**.
@@ -51,8 +53,7 @@ Advanced Tweaks are for users who understand the side effects of deeper Windows
### O&O ShutUp10++
[O&O ShutUp10++](https://www.oo-software.com/en/shutup10) can be launched from WinUtil with one click. It is a free privacy tool for Windows that helps users manage telemetry, update behavior, and app permission settings.
-{{< youtube id=3HvNr8eMcv0 loading=lazy >}}
-
+Watch a walkthrough: [https://www.youtube.com/watch?v=3HvNr8eMcv0](https://www.youtube.com/watch?v=3HvNr8eMcv0)
### DNS
diff --git a/docs/content/userguide/updates/_index.md b/docs/src/content/docs/guides/updates.mdx
similarity index 94%
rename from docs/content/userguide/updates/_index.md
rename to docs/src/content/docs/guides/updates.mdx
index d8f6e02e..49b06c93 100644
--- a/docs/content/userguide/updates/_index.md
+++ b/docs/src/content/docs/guides/updates.mdx
@@ -1,8 +1,8 @@
---
title: Updates
-weight: 6
-prev: /userguide/features/
-next: /userguide/automation/
+description: Choose how aggressively Windows Update is managed on your system with WinUtil's three update modes.
+sidebar:
+ order: 5
---
WinUtil provides three update modes so you can choose how aggressively Windows Update is managed on your system:
diff --git a/docs/content/userguide/win11Creator/_index.md b/docs/src/content/docs/guides/win11creator.mdx
similarity index 70%
rename from docs/content/userguide/win11Creator/_index.md
rename to docs/src/content/docs/guides/win11creator.mdx
index e2c81942..7d112a92 100644
--- a/docs/content/userguide/win11Creator/_index.md
+++ b/docs/src/content/docs/guides/win11creator.mdx
@@ -1,20 +1,25 @@
---
title: Win11 Creator
-weight: 8
-prev: /userguide/automation/
+description: Build a custom, debloated Windows 11 ISO from an official Microsoft image using WinUtil's Win11 Creator tool.
+sidebar:
+ order: 7
---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
## Using WinUtil's Win11 Creator
WinUtil includes a built-in **Win11 Creator** tool that lets you take an official Windows 11 ISO and produce a customized, debloated version. The resulting image can remove telemetry, bypass hardware requirement checks, and enable local account setup out of the box. You can export the result as a new ISO file or write it directly to a USB drive.
-{{< image src="images/win11creator-tab-new" alt="Win11 Creator tab in WinUtil" >}}
+
-> [!IMPORTANT]
-> You need an **official Windows 11 ISO** from [Microsoft's website](https://www.microsoft.com/en-us/software-download/windows11) before starting. Custom, modified, or non-official ISOs are not supported. The process uses ~10β15 GB of temporary disk space, so make sure you have room.
+:::caution
+You need an **official Windows 11 ISO** from [Microsoft's website](https://www.microsoft.com/en-us/software-download/windows11) before starting. Custom, modified, or non-official ISOs are not supported. The process uses ~10β15 GB of temporary disk space, so make sure you have room.
+:::
-> [!NOTE]
-> This workflow is intended for fresh Windows installs, not in-place upgrades of an existing installation.
+:::note
+This workflow is intended for fresh Windows installs, not in-place upgrades of an existing installation.
+:::
---
@@ -32,8 +37,9 @@ WinUtil includes a built-in **Win11 Creator** tool that lets you take an officia
2. WinUtil mounts the ISO, checks for a valid `install.wim` or `install.esd`, and reads the available editions (Home, Pro, Enterprise, etc.).
3. Once verified, select your desired **edition** from the dropdown β Pro is selected by default if available.
-> [!NOTE]
-> This step takes around 10β30 seconds, depending on your drive speed.
+:::note
+This step takes around 10β30 seconds, depending on your drive speed.
+:::
---
@@ -76,32 +82,29 @@ A live log shows progress as each step completes. This stage usually takes **10
Once the modification is complete, choose how to save your image:
-{{< tabs >}}
+
+
+1. Click **Save as an ISO File**.
+2. Choose a save location (defaults to your Desktop as `Win11_Modified_yyyyMMdd.iso`).
+3. WinUtil builds a dual BIOS/UEFI bootable ISO using `oscdimg.exe`.
- {{< tab name="Save as ISO" selected=true >}}
- 1. Click **Save as an ISO File**.
- 2. Choose a save location (defaults to your Desktop as `Win11_Modified_yyyyMMdd.iso`).
- 3. WinUtil builds a dual BIOS/UEFI bootable ISO using `oscdimg.exe`.
+:::note
+`oscdimg.exe` (part of the Windows ADK) is required. If it's not found, WinUtil will attempt to install it automatically via WinGet. If that fails, install it manually: `winget install -e --id Microsoft.OSCDIMG`
+:::
+
+
+1. Click **Write Directly to a USB Drive**.
+2. Select your USB drive from the dropdown (click **Refresh** if it doesn't appear).
+3. Click **Erase & Write to USB** and confirm the warning β **all data on the drive will be permanently erased**.
+4. WinUtil formats the drive as GPT with a 512 MB EFI partition and copies the modified Windows files.
- > [!NOTE]
- > `oscdimg.exe` (part of the Windows ADK) is required. If it's not found, WinUtil will attempt to install it automatically via WinGet. If that fails, install it manually: `winget install -e --id Microsoft.OSCDIMG`
+:::danger
+Double-check you have selected the correct drive before confirming. This operation cannot be undone.
+:::
-
- {{< /tab >}}
-
- {{< tab name="Write to USB" >}}
- 1. Click **Write Directly to a USB Drive**.
- 2. Select your USB drive from the dropdown (click **Refresh** if it doesn't appear).
- 3. Click **Erase & Write to USB** and confirm the warning β **all data on the drive will be permanently erased**.
- 4. WinUtil formats the drive as GPT with a 512 MB EFI partition and copies the modified Windows files.
-
- > [!WARNING]
- > Double-check you have selected the correct drive before confirming. This operation cannot be undone.
-
- **Minimum USB size:** 8 GB recommended. Writing takes 10β20 minutes.
- {{< /tab >}}
-
-{{< /tabs >}}
+**Minimum USB size:** 8 GB recommended. Writing takes 10β20 minutes.
+
+
---
@@ -142,8 +145,10 @@ When you install Windows 11 from your modified ISO:
- Download official Windows 11 media from [Microsoft](https://www.microsoft.com/en-us/software-download/windows11).
- If you prefer to write a finished ISO with another tool, common choices include [Rufus](https://rufus.ie/) or [Ventoy](https://www.ventoy.net/).
-> [!NOTE]
-> Always download Windows ISOs from official Microsoft sources or trusted tools like Rufus/UUP Dump to avoid tampered images.
+:::note
+Always download Windows ISOs from official Microsoft sources or trusted tools like Rufus/UUP Dump to avoid tampered images.
+:::
-> [!NOTE]
-> Newer Windows 11 ISOs may not boot correctly on older versions of Ventoy β make sure Ventoy is up to date before use. If issues persist after updating, this is a Ventoy compatibility limitation outside of WinUtil's control.
+:::note
+Newer Windows 11 ISOs may not boot correctly on older versions of Ventoy β make sure Ventoy is up to date before use. If issues persist after updating, this is a Ventoy compatibility limitation outside of WinUtil's control.
+:::
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
new file mode 100644
index 00000000..5213a4ec
--- /dev/null
+++ b/docs/src/content/docs/index.mdx
@@ -0,0 +1,199 @@
+---
+title: Documentation
+description: Chris Titus Tech's Windows Utility β install apps, apply tweaks, run fixes, and manage Windows from one place.
+template: splash
+editUrl: false
+heroEyebrow: Open Source Windows Setup Utility
+heroCaption: Free. Open source. No installer, no telemetry, no bloat.
+heroBadges:
+ - src: https://img.shields.io/github/v/release/ChrisTitusTech/winutil?color=%230567ff&label=Latest%20Release&style=for-the-badge
+ alt: Latest release
+ href: https://github.com/ChrisTitusTech/winutil/releases/latest
+ - src: https://img.shields.io/github/downloads/ChrisTitusTech/winutil/winutil.ps1?label=Total%20Downloads&style=for-the-badge
+ alt: Total downloads
+ - src: https://dcbadge.limes.pink/api/server/https://discord.gg/RUbZUZyByQ
+ alt: Discord community server
+ href: https://discord.gg/RUbZUZyByQ
+hero:
+ title: Set up Windows the way you actually want it
+ tagline: Install apps, apply tweaks, run fixes, and manage Windows updates β all from one script, one window, no fuss.
+ image:
+ file: ../../assets/branding/title-screen.png
+ actions:
+ - text: Get Started
+ link: /guides/getting-started/
+ icon: right-arrow
+ - text: View on GitHub
+ link: https://github.com/ChrisTitusTech/winutil
+ icon: external
+ variant: secondary
+---
+
+import { Icon, Code } from '@astrojs/starlight/components';
+import CornerCard from '../../components/CornerCard.astro';
+
+{/* Trust bar: icon + label chips under the hero. */}
+
+
+ Open source
+ No installer
+ No telemetry added
+ Everything reversible
+ Windows 11 ready
+
+
+
+{/* Problem section: pain points WinUtil solves. */}
+
+
+
+
Windows setup is easy to start and tedious to finish
+
A fresh install works fine out of the box. Getting it configured the way you actually want takes an afternoon of registry edits, forum posts, and forgotten steps.
+
+
+ - Essential apps mean a dozen separate installers, each with its own bundled toolbar to decline.
+ - Privacy and telemetry settings are scattered across half a dozen different settings panels.
+ - The tweaks worth applying live in year-old forum threads, mixed in with outdated or risky advice.
+ - Undoing a tweak means remembering exactly what you changed and how.
+ - Doing it all again on the next machine means starting from zero.
+
+
+
+
WinUtil puts a real control panel on top of Windows
+
Instead of stitching together installers, registry hacks, and forum wisdom, you manage the whole setup from one window.
+
+
+
+
+
Install without the bloat
+
WinGet and Chocolatey install clean builds of your everyday apps, with no bundled toolbars or bundled offers.
+
+
+
+
Tweak with a checkbox
+
Essential and advanced tweaks for privacy, performance, and UI behavior are one click away, grouped by what they actually do.
+
+
+
+
Undo what you don't like
+
Nearly every tweak can be reverted from the same panel, so trying something risky doesn't mean a full reinstall.
+
+
+
+
Fix what's broken
+
One-click repairs for networking, Windows Update, and WinGet handle the fixes people usually paste from a forum thread.
+
+
+
+
Manage updates your way
+
Switch between full updates, security-only updates, or fully paused β and back again β without digging through Group Policy.
+
+
+
+
Build your own ISO
+
Win11 Creator debloats and preconfigures an official Microsoft image, so new installs start from your baseline.
+
+
+
+
+
Everything you need to set up a machine, once
+
+
+
+ WinUtil doesn't collect or transmit anything. It's a script that runs, makes the changes you selected, and exits.
+
+
+ Tweaks are applied through documented, undoable actions instead of one-way registry edits.
+
+
+ Minimal, Standard, and Advanced presets give you a sane starting point instead of picking through every tweak individually.
+
+
+ Application installs go through package managers you can audit, not opaque bundled installers.
+
+
+ Drive WinUtil unattended with config files and parameters for repeatable rollouts across machines.
+
+
+ Debloat and preconfigure a Windows 11 image before it's ever installed.
+
+
+
+
+
From a blank terminal to a configured PC
+
+
+
+
1
+
Open PowerShell as Administrator
+
Right-click the Start button and choose Terminal (Admin), or launch PowerShell and elevate manually.
+
+
+
2
+
Run the launch command
+
Downloads and starts the latest release.
+
+
+
+
3
+
Install, tweak, fix, update
+
Work through the Install, Tweaks, Config, and Updates tabs β everything is undoable.
+
+
+
+
+
+
Built for the gap between a fresh install and a finished machine
+
Registry edits and PowerShell one-liners work. WinUtil makes them repeatable.
+
+
+ - You keep full control β every tweak is visible, documented, and reversible.
+ - You gain a single interface for installs, tweaks, fixes, and updates instead of five different tools.
+ - You avoid the bundled toolbars and bloat that come with most software installers.
+
+
+
Stop hunting for the same fixes every time
+
Get a script that installs, tweaks, fixes, and updates Windows from one window.
+
+
+
MDX wraps around icon+text content, so it never breaks the flex row. */
+.wu-btn > p,
+.wu-trust-item > p {
+ display: contents;
+}
+
+/* Cancels Starlight's automatic 1.5rem inter-block margin inside our own grids/rows (it otherwise lands on item 2+ of each row and breaks alignment). */
+.sl-markdown-content .wu-section,
+.sl-markdown-content .wu-solution-grid > *,
+.sl-markdown-content .wu-feature-grid > *,
+.sl-markdown-content .wu-timeline > *,
+.sl-markdown-content .wu-problem-list > *,
+.sl-markdown-content .wu-benefit-list > *,
+.sl-markdown-content .wu-trust-bar > *,
+.sl-markdown-content .wu-badges > *,
+.sl-markdown-content .wu-btn-row > * {
+ margin-top: 0;
+}
+
+/* Section shell: full-bleed hairline dividers, alternating tint, 72rem reading width. */
+.wu-section {
+ margin-inline: calc(-1 * var(--sl-content-pad-x));
+ padding-inline: var(--sl-content-pad-x);
+ border-bottom: 1px solid var(--sl-color-hairline-light);
+ padding-block: clamp(3rem, 4vw + 1.5rem, 5.5rem);
+}
+.wu-section--trust {
+ padding-block: 2rem;
+}
+.wu-section--tint {
+ background-color: var(--sl-color-gray-7, var(--sl-color-gray-6));
+}
+:root:not([data-theme='light']) .wu-section--tint {
+ background-color: color-mix(in srgb, var(--sl-color-gray-6) 60%, transparent);
+}
+.wu-section-inner {
+ max-width: 72rem;
+ margin-inline: auto;
+}
+.wu-text-narrow {
+ max-width: 44rem;
+ margin-inline: auto;
+}
+
+.wu-section-head {
+ max-width: 42rem;
+ margin: 0 auto 2.5rem;
+ text-align: center;
+}
+.wu-section-head h2 {
+ margin: 0;
+ font-size: var(--sl-text-3xl);
+ font-weight: 700;
+ letter-spacing: -0.01em;
+ color: var(--sl-color-white);
+}
+.wu-section-head p {
+ margin: 0.75rem 0 0;
+ font-size: var(--sl-text-lg);
+ color: var(--sl-color-gray-3);
+}
+.wu-section-head.wu-align-left {
+ text-align: left;
+ margin-inline: 0;
+ max-width: none;
+}
+
+/* Shields.io / dcbadge release, download, and Discord badges. */
+.wu-badges {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: center;
+ align-items: center;
+ gap: 0.5rem;
+ margin-bottom: 1.5rem;
+}
+.wu-badges img {
+ height: 1.75rem;
+ width: auto;
+ display: block;
+}
+
+/* Trust bar: icon + label chips under the hero. */
+.wu-trust-bar {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: center;
+ align-items: center;
+ gap: 0.75rem 1.25rem;
+}
+.wu-trust-item {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ font-size: var(--sl-text-sm);
+ font-weight: 500;
+ color: var(--sl-color-gray-3);
+}
+.wu-trust-item svg {
+ color: var(--sl-color-accent);
+ width: 1rem;
+ height: 1rem;
+}
+
+/* Problem list: bullet-circle + text, left aligned. */
+.wu-problem-list {
+ display: flex;
+ flex-direction: column;
+ gap: 1.1rem;
+ margin: 2.5rem 0 0;
+ padding: 0;
+ list-style: none;
+}
+.wu-problem-list li {
+ display: flex;
+ align-items: flex-start;
+ gap: 1rem;
+ color: var(--sl-color-gray-3);
+}
+.wu-problem-list .wu-bullet {
+ flex: none;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.5rem;
+ height: 1.5rem;
+ margin-top: 0.15rem;
+ border-radius: 999px;
+ background: var(--sl-color-gray-6);
+}
+.wu-problem-list .wu-bullet svg {
+ width: 0.85rem;
+ height: 0.85rem;
+ color: var(--sl-color-gray-3);
+}
+
+/* Solution grid: icon-in-box above title + description. */
+.wu-solution-grid {
+ display: grid;
+ gap: 2rem;
+ margin-top: 3rem;
+}
+.wu-solution {
+ display: flex;
+ flex-direction: column;
+ gap: 0.75rem;
+}
+.wu-solution-icon {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 2.5rem;
+ height: 2.5rem;
+ border-radius: var(--wu-radius-sm);
+ background: var(--sl-color-gray-6);
+ color: var(--sl-color-accent);
+}
+.wu-solution h3 {
+ margin: 0;
+ font-size: var(--sl-text-lg);
+ font-weight: 600;
+ color: var(--sl-color-white);
+}
+.wu-solution p {
+ margin: 0;
+ font-size: var(--sl-text-sm);
+ line-height: var(--sl-line-height);
+ color: var(--sl-color-gray-3);
+}
+
+/* Feature grid: wraps instances. */
+.wu-feature-grid {
+ display: grid;
+ gap: 1.25rem;
+ margin-top: 3rem;
+}
+
+/* Step timeline ("how it works"): connecting line through each numbered circle. */
+.wu-timeline {
+ position: relative;
+ max-width: 36rem;
+ margin: 3rem auto 0;
+ display: flex;
+ flex-direction: column;
+ gap: 2rem;
+}
+.wu-timeline::before {
+ content: '';
+ position: absolute;
+ left: 1.25rem;
+ top: 1.25rem;
+ bottom: 1.25rem;
+ width: 1px;
+ background: var(--sl-color-hairline-light);
+}
+.wu-timeline-step {
+ position: relative;
+ display: flex;
+ flex-direction: column;
+ gap: 0.5rem;
+ padding-left: 3.5rem;
+}
+.wu-timeline-number {
+ position: absolute;
+ left: 0;
+ top: 0;
+ z-index: 1;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 2.5rem;
+ height: 2.5rem;
+ border-radius: 999px;
+ border: 1px solid var(--sl-color-hairline-light);
+ background: var(--sl-color-bg);
+ font-weight: 700;
+ color: var(--sl-color-accent);
+}
+.wu-timeline-step h3 {
+ margin: 0;
+ font-size: var(--sl-text-lg);
+ font-weight: 600;
+ color: var(--sl-color-white);
+}
+.wu-timeline-step p {
+ margin: 0;
+ color: var(--sl-color-gray-3);
+}
+.wu-timeline-step code {
+ border-radius: var(--wu-radius-sm);
+}
+
+/* Benefit checklist. */
+.wu-benefit-list {
+ display: flex;
+ flex-direction: column;
+ gap: 1rem;
+ margin: 2.5rem 0 0;
+ padding: 0;
+ list-style: none;
+}
+.wu-benefit-list li {
+ display: flex;
+ align-items: flex-start;
+ gap: 1rem;
+ color: var(--sl-color-white);
+}
+.wu-benefit-list .wu-check {
+ flex: none;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.5rem;
+ height: 1.5rem;
+ margin-top: 0.15rem;
+ border-radius: 999px;
+ background: hsl(var(--wu-accent-h) 100% 51% / 0.12);
+}
+.wu-benefit-list .wu-check svg {
+ width: 0.85rem;
+ height: 0.85rem;
+ color: var(--sl-color-accent);
+}
+
+/* Final call to action. */
+.wu-cta {
+ text-align: center;
+}
+.wu-cta h2 {
+ margin: 0;
+ font-size: var(--sl-text-3xl);
+ font-weight: 700;
+ letter-spacing: -0.01em;
+ color: var(--sl-color-white);
+}
+.wu-cta > p:first-of-type {
+ margin: 0.75rem 0 0;
+ font-size: var(--sl-text-lg);
+ color: var(--sl-color-gray-3);
+}
+.wu-cta .wu-btn-row {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: center;
+ gap: 0.75rem;
+ margin-top: 2rem;
+}
+.wu-cta p.wu-cta-footnote {
+ margin-top: 2rem;
+ font-size: var(--sl-text-sm);
+ color: var(--sl-color-gray-3);
+}
+
+/* Grid breakpoints: 1 col mobile, 2 col tablet, 3 col desktop. */
+@media (min-width: 40em) {
+ .wu-solution-grid {
+ grid-template-columns: repeat(2, 1fr);
+ }
+ .wu-feature-grid {
+ grid-template-columns: repeat(2, 1fr);
+ }
+}
+@media (min-width: 60em) {
+ .wu-solution-grid {
+ grid-template-columns: repeat(3, 1fr);
+ }
+ .wu-feature-grid {
+ grid-template-columns: repeat(3, 1fr);
+ }
+ .wu-timeline {
+ gap: 2.5rem;
+ }
+}
diff --git a/docs/static/CNAME b/docs/static/CNAME
deleted file mode 100644
index 5c5e6a6d..00000000
--- a/docs/static/CNAME
+++ /dev/null
@@ -1 +0,0 @@
-winutil.christitus.com
diff --git a/docs/static/android-chrome-192x192.png b/docs/static/android-chrome-192x192.png
deleted file mode 100644
index 0fe939a7..00000000
Binary files a/docs/static/android-chrome-192x192.png and /dev/null differ
diff --git a/docs/static/android-chrome-512x512.png b/docs/static/android-chrome-512x512.png
deleted file mode 100644
index 33d192ca..00000000
Binary files a/docs/static/android-chrome-512x512.png and /dev/null differ
diff --git a/docs/static/apple-touch-icon.png b/docs/static/apple-touch-icon.png
deleted file mode 100644
index 9ffa9952..00000000
Binary files a/docs/static/apple-touch-icon.png and /dev/null differ
diff --git a/docs/static/favicon-16x16.png b/docs/static/favicon-16x16.png
deleted file mode 100644
index f4760305..00000000
Binary files a/docs/static/favicon-16x16.png and /dev/null differ
diff --git a/docs/static/favicon-32x32.png b/docs/static/favicon-32x32.png
deleted file mode 100644
index 5532ef6c..00000000
Binary files a/docs/static/favicon-32x32.png and /dev/null differ
diff --git a/docs/static/favicon.ico b/docs/static/favicon.ico
deleted file mode 100644
index f95955c6..00000000
Binary files a/docs/static/favicon.ico and /dev/null differ
diff --git a/docs/static/site.webmanifest b/docs/static/site.webmanifest
deleted file mode 100644
index 1dd91123..00000000
--- a/docs/static/site.webmanifest
+++ /dev/null
@@ -1 +0,0 @@
-{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
new file mode 100644
index 00000000..8bf91d3b
--- /dev/null
+++ b/docs/tsconfig.json
@@ -0,0 +1,5 @@
+{
+ "extends": "astro/tsconfigs/strict",
+ "include": [".astro/types.d.ts", "**/*"],
+ "exclude": ["dist"]
+}
diff --git a/tools/devdocs-generator.md b/tools/devdocs-generator.md
index 41d56d3b..d89794b8 100644
--- a/tools/devdocs-generator.md
+++ b/tools/devdocs-generator.md
@@ -5,11 +5,11 @@ 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.
+The `devdocs-generator.ps1` script automatically generates Astro/Starlight markdown (`.mdx`) 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 triggered by the `docs.yaml` GitHub Actions workflow, which generates the `.md` files, commits them back to the repo, and then triggers Hugo to build the site
+- Automatically triggered by the `docs.yaml` GitHub Actions workflow, which generates the `.mdx` files, commits them back to the repo, and then triggers the Astro build to build the site
- Automatically runs during the pre-release workflow, committing the updated `"link"` properties back to the JSON config files
- Watches `docs/**`, `config/tweaks.json`, `config/feature.json`, and `functions/**` for changes
- Supports manual runs via `workflow_dispatch`
@@ -30,8 +30,9 @@ The `devdocs-generator.ps1` script automatically generates Hugo-compatible markd
### 3. Cleans Up Old Docs
-- Deletes all `.md` files (except `_index.md`) from `docs/content/dev/tweaks/` and `docs/content/dev/features/`
+- Deletes all `.mdx` files from `docs/src/content/docs/code-reference/tweaks/` and `docs/src/content/docs/code-reference/features/`
- This prevents duplicate or orphaned files from previous runs
+- No category `index.mdx` landing pages exist yet; if one is added later, the matching exclusion in the script is left commented out ready to re-enable
### 4. Generates Tweak Documentation
@@ -40,7 +41,6 @@ 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
@@ -51,8 +51,9 @@ For each entry in `feature.json` that belongs to a documented category:
### 6. Output Format
-- Every `.md` file gets Hugo frontmatter with `title` and `description`
-- Code blocks use Hugo syntax with filename labels and line numbers
+- Every `.mdx` file gets Starlight frontmatter with `title` and `description` (description comes from the entry's `Description` field when present)
+- A `:::note` aside points back at the source file (JSON config or PowerShell function) it was generated from
+- Code blocks use Starlight/Expressive Code syntax with a `title` attribute naming the source file
- Files are organized into category subdirectories matching the JSON `category` field
## Documented Categories
@@ -70,7 +71,7 @@ The script generates docs for entries in these categories:
## File Structure
```
-docs/content/dev/
+docs/src/content/docs/code-reference/
tweaks/
Essential-Tweaks/
z--Advanced-Tweaks---CAUTION/
@@ -82,24 +83,26 @@ docs/content/dev/
Legacy-Windows-Panels/
```
+The Starlight sidebar picks these up automatically via `autogenerate` entries in `docs/astro.config.mjs` for the `code-reference/tweaks` and `code-reference/features` directories, so no sidebar edits are needed when new entries are added.
+
## 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` |
+| `WPFTweaksHiber` | `Hiber.mdx` |
+| `WPFTweaksDeBloat` | `DeBloat.mdx` |
+| `WPFFeatureshyperv` | `hyperv.mdx` |
+| `WPFPanelDISM` | `DISM.mdx` |
## 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 modify `_index.md` or `architecture.md`
- β do not delete `_index.md` or `architecture.md`, as they will need to be recreated manually.
+- Manual edits to generated `.mdx` files will be overwritten on the next run
+- The script only touches `docs/src/content/docs/code-reference/tweaks/` and `.../features/` β `architecture.mdx` and any other hand-written page under `code-reference/` are untouched
+ β if a category `index.mdx` landing page is added inside `tweaks/` or `features/`, uncomment the exclusion in the cleanup step first, or it will be deleted on the next run
- Category directories are created automatically if they don't exist
- The `"link"` property added to JSON entries is excluded from the displayed code blocks
-- The `docs` workflow generates the `.md` files and commits them back to the repo before Hugo builds the site
+- The `docs` workflow generates the `.mdx` files and commits them back to the repo before the Astro site is built
- The `pre-release` workflow generates the `"link"` properties and commits them back to the repo
diff --git a/tools/devdocs-generator.ps1 b/tools/devdocs-generator.ps1
index ab9b1adc..e3422a55 100644
--- a/tools/devdocs-generator.ps1
+++ b/tools/devdocs-generator.ps1
@@ -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"
}
- 
-