diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 07242343..f0bb5a50 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -5,13 +5,13 @@ * Test the latest changes to WinUtil by running the pre-release and reporting issues you are encountering to help us continually improve WinUtil! #### **Run the latest pre-release** - ```ps1 - irm https://christitus.com/windev | iex - ``` -!!! bug "Keep in mind" +```ps1 +irm https://christitus.com/windev | iex +``` - This is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production! +> [!CAUTION] +> **Keep in mind:** This is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production! ## Issues @@ -23,19 +23,17 @@ * If you're doing code changes, then you can submit a PR to the `main` branch. -!!! warning "Important" - - Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE IT'S OWN PULL REQUEST! - - Do not open a pull request that adds support for other languages to WinUtil for now, until we decide how we want to move forward with language support. +> [!IMPORTANT] +> Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE ITS OWN PULL REQUEST! +> +> Do not open a pull request that adds support for other languages to WinUtil for now, until we decide how we want to move forward with language support. * When creating pull requests, it is essential to thoroughly document all changes made. This includes, but is not limited to, documenting any additions made to the `tweaks` section and corresponding `undo tweak`, so users are able to remove the newly added tweaks if necessary, and comprehensive documentation is required for all code changes. Document your changes and briefly explain why you made your changes in your Pull Request Description. Failure to adhere to this format may result in the denial of the pull request. Additionally, any code lacking sufficient documentation may also be denied. * By following these guidelines, we can maintain a high standard of quality and ensure that the codebase remains organized and well-documented. -!!! note - - When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace. +> [!NOTE] +> When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace. ## Walk through @@ -47,37 +45,34 @@ ### Overview -``` mermaid +```mermaid %%{init: {"flowchart": {"curve": "cardinal"}} }%% graph TD -  A[Fork Project] --> B[Clone Repository]; -  B --> C[Create New Branch]; -  C --> D[Make Changes]; -  D --> G[Test Changes]; -  G --> H{Tests Passed?}; -  H -->|Yes| E[Commit Changes]; -  H -->|No| J[Fix Issues]; -  J --> G; -  E --> F[Push Branch]; -  F --> K[Create Pull Request]; -  K --> L[Fill out PR template]; + A[Fork Project] --> B[Clone Repository]; + B --> C[Create New Branch]; + C --> D[Make Changes]; + D --> G[Test Changes]; + G --> H{Tests Passed?}; + H -->|Yes| E[Commit Changes]; + H -->|No| J[Fix Issues]; + J --> G; + E --> F[Push Branch]; + F --> K[Create Pull Request]; + K --> L[Fill out PR template]; classDef default stroke:#333,stroke-width:4px,font-size:12pt; ``` -!!! info - This is a diagram to guide you through the process. It may vary depending on the type of change you're making. +> [!NOTE] +> This is a diagram to guide you through the process. It may vary depending on the type of change you're making. ### Fork the Repo * Fork the WinUtil Repository [here](https://github.com/ChrisTitusTech/winutil) to create a copy that will be available in your repository list. -![Fork Image](/docs/assets/images/Fork-Button-Dark.png#gh-dark-mode-only) - -![Fork Image](/docs/assets/images/Fork-Button-Light.png#only-light#gh-light-mode-only) +![Fork Image](../docs/src/assets/contributing/Fork-Button-Dark.png) ### Clone the Fork -!!! tip - - While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily. +> [!TIP] +> While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily. * Install GitHub Desktop if it is not already installed. * Log in using the same GitHub account you used to fork WinUtil. @@ -96,7 +91,7 @@ graph TD * Run the following command to compile and run WinUtil: * `.\Compile.ps1 -run` -![Compile](/docs/assets/images/Complie.png) +![Compile](../docs/src/assets/contributing/Complie.png) Open PowerShell as Administrator. @@ -107,15 +102,15 @@ Open PowerShell as Administrator. ### Committing the changes * Before committing your changes, please discard changes made to the `winutil.ps1` file, like the following: -![Push Commit Image](/docs/assets/images/Discard-GHD.png) +![Push Commit Image](../docs/src/assets/contributing/Discard-GHD.png) * Now, commit your changes once you are happy with the result. -![Commit Image](/docs/assets/images/Commit-GHD.png) +![Commit Image](../docs/src/assets/contributing/Commit-GHD.png) -* Push the changes to upload them to your fork on github.com. +* Push the changes to upload them to your fork on GitHub. -![Push Commit Image](/docs/assets/images/Push-Commit.png) +![Push Commit Image](../docs/src/assets/contributing/Push-Commit.png) ### Making a PR * To make a PR on your repo under a new branch linking to the main branch, a button will show and say Preview and Create pull request. Click that button and fill in all the information that is provided on the template. Once all the information is filled in correctly, check your PR to make sure there is no WinUtil.ps1 file attached to the PR. Once everything is good, make the PR and wait for Chris (the maintainer) to accept or deny your PR. Once it is accepted by Chris, you will be able to see your changes in the "/windev" build. diff --git a/.github/READMEITALIAN.md b/.github/READMEITALIAN.md index a5a71830..7356b22e 100644 --- a/.github/READMEITALIAN.md +++ b/.github/READMEITALIAN.md @@ -7,7 +7,7 @@ Questa utility è una raccolta di attività Windows che eseguo personalmente su ogni sistema che utilizzo. È progettata per snellire le *installazioni*, rimuovere i componenti superflui tramite *ottimizzazioni*, risolvere problemi tramite la *configurazione*, e riparare *aggiornamenti* di Windows. Sono estremamente selettivo riguardo ai contributi per mantenere questo progetto pulito ed efficiente. -![screen-install](/docs/assets/images/Title-Screen.png) +![screen-install](../docs/src/assets/branding/title-screen.png) ## 💡 Come usarlo diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 798b223d..c1f1c265 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -6,25 +6,17 @@ on: - main paths: - "docs/**" - - "config/tweaks.json" - - "config/feature.json" - - "functions/**" workflow_dispatch: permissions: contents: read pages: write id-token: write - pull-requests: write concurrency: group: "pages" cancel-in-progress: false -defaults: - run: - shell: bash - jobs: build: if: github.repository == 'ChrisTitusTech/winutil' @@ -38,36 +30,6 @@ jobs: fetch-depth: 0 persist-credentials: false - - name: Generate Dev Docs from JSON - shell: pwsh - run: | - Set-Location tools - ./devdocs-generator.ps1 - - - name: Create Pull Request - id: cpr - uses: peter-evans/create-pull-request@v8 - with: - token: ${{ secrets.AUTO_MERGE }} - commit-message: 'chore: Update generated dev docs' - title: 'chore: Update Generated Dev Docs' - body: 'Automated update of generated documentation from JSON sources' - branch: docs-update - delete-branch: true - add-paths: | - docs/src/content/docs/code-reference/ - config/tweaks.json - config/feature.json - labels: | - automated - documentation - skip-changelog - - - name: Check outputs - run: | - echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}" - echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}" - - name: Install, build, and upload your site uses: withastro/action@v6 with: diff --git a/.github/workflows/pre-release.yaml b/.github/workflows/pre-release.yaml index 4757555b..26ca4dee 100644 --- a/.github/workflows/pre-release.yaml +++ b/.github/workflows/pre-release.yaml @@ -31,21 +31,23 @@ jobs: Set-ExecutionPolicy Bypass -Scope Process -Force; ./Compile.ps1 continue-on-error: false # Directly fail the job on error, removing the need for a separate check - - name: Create Pull Request for Updated JSON Links + - name: Create Pull Request for Updated Docs and JSON Links id: cpr uses: peter-evans/create-pull-request@v8 with: token: ${{ secrets.AUTO_MERGE }} - commit-message: 'chore: Update documentation links in JSON configs' - title: 'chore: Update documentation links in JSON configs' - body: 'Automated update of documentation links in JSON configs from pre-release build' + commit-message: 'chore: Update generated dev docs and JSON links' + title: 'chore: Update generated dev docs and JSON links' + body: 'Automated update of generated documentation and JSON config links from pre-release build' branch: docs-update delete-branch: true add-paths: | + docs/src/content/docs/code-reference/ config/tweaks.json config/feature.json labels: | automated + documentation skip-changelog - name: Check outputs diff --git a/README.md b/README.md index aba04320..dd9d2aec 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A curated compilation of Windows system tasks streamline **installs**, debloat with **tweaks**, troubleshoot with **config**, and configure **Windows updates**. Run it fresh on every new Windows install. -image +![Title Screen](docs/src/assets/branding/title-screen.png) --- diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 63201b5b..88b8b0bb 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -18,16 +18,19 @@ export default defineConfig({ { icon: 'github', label: 'GitHub', href: 'https://github.com/ChrisTitusTech/winutil' }, { icon: 'discord', label: 'Discord', href: 'https://discord.gg/RUbZUZyByQ' }, ], + // Global theme overrides (colors, fonts, landing-page section styles). customCss: ['./src/styles/theme.css'], + // Custom component overrides, all under src/components/. components: { ThemeProvider: './src/components/ThemeProvider.astro', - Hero: './src/components/Hero.astro', Header: './src/components/Header.astro', + Hero: './src/components/Hero.astro', Footer: './src/components/Footer.astro', }, editLink: { baseUrl: 'https://github.com/ChrisTitusTech/winutil/edit/main/docs/', }, + // Sidebar groups, top to bottom: User Guide, Code Reference, Help. sidebar: [ { label: 'User Guide', @@ -54,7 +57,7 @@ export default defineConfig({ label: 'Help', items: [ { label: 'FAQ', slug: 'faq' }, - { label: 'Known Issues', slug: 'known-issues' }, + { label: 'Known Issues', slug: 'knownissues' }, { label: 'Contributing', slug: 'contributing' }, ], }, diff --git a/docs/src/assets/houston.webp b/docs/src/assets/houston.webp deleted file mode 100644 index 930c1649..00000000 Binary files a/docs/src/assets/houston.webp and /dev/null differ diff --git a/docs/src/components/CornerCard.astro b/docs/src/components/CornerCard.astro index 6dae451f..951c5f03 100644 --- a/docs/src/components/CornerCard.astro +++ b/docs/src/components/CornerCard.astro @@ -12,11 +12,13 @@ const { icon, title } = Astro.props; ---
+ {/* Corner brackets decoration. */}
- - Read the Docs - + + {'Read the Docs'} +
@@ -185,7 +185,7 @@ import CornerCard from '../../components/CornerCard.astro';

Stop hunting for the same fixes every time

Get a script that installs, tweaks, fixes, and updates Windows from one window.

- + {'Get Started'} diff --git a/docs/src/content/docs/known-issues.mdx b/docs/src/content/docs/knownissues.mdx similarity index 100% rename from docs/src/content/docs/known-issues.mdx rename to docs/src/content/docs/knownissues.mdx diff --git a/docs/src/styles/theme.css b/docs/src/styles/theme.css index 90b92b45..4a716a2e 100644 --- a/docs/src/styles/theme.css +++ b/docs/src/styles/theme.css @@ -139,8 +139,7 @@ body { border-color 0.15s ease, color 0.15s ease; } -/* The right/left-arrow glyph's visual weight sits high in its viewBox, so it - reads as floating above the label's baseline without this nudge. */ +/* The right/left-arrow glyph's visual weight sits high in its viewBox, so it reads as floating above the label's baseline without this nudge. */ .wu-btn .wu-icon-arrow { position: relative; top: 0.05em; @@ -155,7 +154,7 @@ body { .wu-btn-secondary { border: 1px solid var(--sl-color-hairline-light); color: var(--sl-color-white); - background: transparent; + background: var(--sl-color-gray-6); } .wu-btn-secondary:hover { border-color: var(--sl-color-accent); @@ -167,6 +166,11 @@ body { display: contents; } +/* Cancels Starlight's automatic 1.5rem margin between the hero and the content column. */ +.wu-hero + .sl-markdown-content { + margin-top: 0; +} + /* 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 > *, @@ -188,6 +192,9 @@ body { padding-block: clamp(3rem, 4vw + 1.5rem, 5.5rem); } .wu-section--trust { + display: flex; + align-items: center; + justify-content: center; padding-block: 2rem; } .wu-section--tint { diff --git a/tools/devdocs-generator.md b/tools/devdocs-generator.md index d89794b8..168a1ec1 100644 --- a/tools/devdocs-generator.md +++ b/tools/devdocs-generator.md @@ -9,10 +9,10 @@ The `devdocs-generator.ps1` script automatically generates Astro/Starlight markd ## When Does it Run? -- 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` +- Automatically runs as part of the `pre-release.yaml` GitHub Actions workflow (manually triggered via `workflow_dispatch`), which regenerates the `.mdx` files and updates the `"link"` properties in the JSON config files +- `pre-release.yaml` then opens a `docs-update` pull request with those changes; `auto-merge-docs.yaml` auto-approves and merges it into `main` +- That merge pushes changes under `docs/**`, which triggers `docs.yaml` — but `docs.yaml` only builds and deploys the Astro site, it does not run the generator itself +- Can also be run manually/locally from `tools/` (`./devdocs-generator.ps1`) ## What Does It Do? @@ -25,7 +25,7 @@ The `devdocs-generator.ps1` script automatically generates Astro/Starlight markd ### 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 +- Each link points to that entry's documentation page on the Astro/Starlight site - The updated links are automatically committed back to the JSON config files as part of the pre-release workflow ### 3. Cleans Up Old Docs @@ -104,5 +104,5 @@ The script strips common prefixes from the JSON key names using the pattern `WPF — 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 `.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 +- The `pre-release` workflow generates both the `.mdx` files and the `"link"` properties, and commits them back to the repo via the `docs-update` PR +- The `docs` workflow never runs the generator — it only builds and deploys the already-committed Astro site diff --git a/tools/devdocs-generator.ps1 b/tools/devdocs-generator.ps1 index e3422a55..219d9f9b 100644 --- a/tools/devdocs-generator.ps1 +++ b/tools/devdocs-generator.ps1 @@ -100,7 +100,7 @@ function Get-GeneratedFromNote { $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 += "This page is generated from [``$SourceRelativePath``]($githubUrl). Do not edit this page directly.`r`n" $note += ":::`r`n`r`n" return $note } @@ -347,7 +347,7 @@ foreach ($itemName in $tweakNames) { $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" + $content = "---`r`ntitle: `"$title`"`r`ndescription: `"$description`"`r`neditUrl: false`r`n---`r`n`r`n" if ($item.Type -eq "Button") { $funcName = $buttonFunctionMap[$itemName] @@ -406,7 +406,7 @@ foreach ($itemName in $featureNames) { $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" + $content = "---`r`ntitle: `"$title`"`r`ndescription: `"$description`"`r`neditUrl: false`r`n---`r`n`r`n" if ($item.category -in $functionEmbedCategories) { $funcName = if ($item.function) { $item.function } else { $buttonFunctionMap[$itemName] }