August Blog Update

.github/copilot-instructions.md

@@ -0,0 +1,144 @@
+# Copilot Instructions for psake Documentation Site
+
+## Project Overview
+This is a **Docusaurus-based documentation site** for [psake](https://github.com/psake/psake), a PowerShell build automation tool. The site combines static documentation, auto-generated command references, and a blog using a hybrid PowerShell/Node.js build system.
+
+## Architecture & Key Components
+
+### Build System (PowerShell + psake)
+- **Entry point**: `build.ps1` - main build orchestrator using psake tasks
+- **Task definitions**: `psakeFile.ps1` - contains all build tasks and automation
+- **Dependencies**: `requirements.psd1` - PowerShell module dependencies managed via PSDepend
+- **Key tasks**: `Init` (yarn install), `Build` (full site), `Server` (dev server), `Test` (Pester tests)
+
+### Content Management
+- **Docs**: `/docs/` - structured tutorials and guides (Markdown)
+- **Blog**: `/blog/` - timestamped posts with frontmatter metadata
+- **Command reference**: Auto-generated from psake module using `Alt3.Docusaurus.Powershell`
+- **Data files**: `blog/authors.yml` and `blog/tags.yml` (YAML format, synced to JSON for Frontmatter CMS)
+
+### Frontmatter CMS Integration
+- **Config**: `frontmatter.json` - defines content types, fields, and datafile mappings
+- **Data sync**: psake task `FrontMatterCMSSync` converts YAML→JSON for CMS consumption
+- **Author/tag management**: Uses datafiles with `handle` as labelField for dropdowns
+
+## Development Workflows
+
+### Quick Start
+```powershell
+# Bootstrap dependencies (first time only)
+.\build.ps1 -Bootstrap
+
+# Start development server
+.\build.ps1 -Task Server
+```
+
+### Build & Test
+```powershell
+# Full build (includes command reference generation)
+.\build.ps1 -Task Build
+
+# Run tests (validates sidebar links)
+.\build.ps1 -Task Test
+
+# List all available tasks
+.\build.ps1 -Help
+```
+
+### Command Reference Generation
+The site auto-generates MDX files for psake commands:
+- Source: psake PowerShell module help
+- Generator: `New-DocusaurusHelp` from Alt3.Docusaurus.Powershell
+- Output: `docs/commands/*.mdx` with automatic cross-reference link fixing
+- Sidebar: Auto-imported via `docs/commands/docusaurus.sidebar.js`
+
+## Key Conventions
+
+### Content Structure
+- **Tutorials**: Follow `tutorial-basics/` and `tutorial-advanced/` patterns
+- **Categories**: Use `_category_.json` files for folder metadata
+- **Blog posts**: Format: `YYYY-MM-DD-title.md` with required frontmatter fields
+- **Sidebar**: Manually maintained in `sidebars.ts` (validated by tests)
+
+### Data Management
+- **Authors**: Define in `blog/authors.yml` with handle as key
+- **Tags**: Define in `blog/tags.yml` with label, permalink, description
+- **Sync process**: YAML files are source of truth, JSON files are generated
+
+### Frontmatter Fields
+- **Blog posts**: Use `authors` and `tags` arrays with handle values
+- **Docs**: Support full Docusaurus metadata (sidebar_position, etc.)
+- **Content types**: Different field sets for blog, docs, pages
+
+### Blog Post Frontmatter Best Practices
+**Required fields for all blog posts:**
+```yaml
+---
+title: "Clear, descriptive title"
+description: "SEO-friendly description (150-160 chars recommended)"
+date: 2025-08-03T23:38:05.100Z  # Auto-generated, use ISO format
+authors:
+  - heyitsgilbert  # Use author handle from blog/authors.yml
+tags:
+  - psake          # Use tag handles from blog/tags.yml
+  - announcement   # Multiple tags recommended for discoverability
+---
+```
+
+**File naming convention:** `YYYY-MM-DD-slug-title.md` (date prefix required)
+
+**Content structure:**
+- Start with engaging intro paragraph
+- Add `<!-- truncate -->` after first paragraph for blog list previews
+- Use semantic headings (## for main sections)
+- Include code examples with proper language tags
+
+**Available tag handles:**
+- `powershell`, `build-automation`, `psake`, `ci-cd`
+- `testing`, `deployment`, `scripting`, `tutorial`
+- `getting-started`, `advanced`, `best-practices`, `tips`
+- `troubleshooting`, `release`, `announcement`
+- `msbuild`, `dotnet`, `visual-studio`
+
+**Optional but recommended fields:**
+- `slug`: Custom URL (auto-generated from filename if omitted)
+- `image`: Social media preview image
+- `keywords`: Additional SEO keywords array
+- `draft: true`: Hide from production until ready
+
+## Testing & Quality
+- **Pester tests**: Validate all docs are linked in sidebar (`tests/Docs.Tests.ps1`)
+- **Build validation**: Yarn build fails on broken links
+- **Content validation**: Frontmatter CMS enforces field requirements
+
+## Deployment
+- **Platform**: Netlify (auto-deploy from main branch)
+- **Build command**: `.\build.ps1 -Task Build` (generates static site to `/build`)
+- **Preview**: Local server on http://localhost:3000
+
+## File Patterns to Follow
+- **New tutorials**: Add to appropriate category in `sidebars.ts`
+- **New blog posts**: Use existing post as template, update authors/tags arrays
+- **Command docs**: Auto-generated, edit source help in psake repo
+- **Data changes**: Edit YAML files, run `FrontMatterCMSSync` task to regenerate JSON
+
+### Blog Post Creation Checklist
+1. **File naming**: Use `YYYY-MM-DD-descriptive-slug.md` format
+2. **Frontmatter validation**: Ensure all required fields are present
+3. **Author verification**: Confirm author handle exists in `blog/authors.yml`
+4. **Tag validation**: Use only handles defined in `blog/tags.yml`
+5. **Content structure**: Include intro + `<!-- truncate -->` + main content
+6. **SEO optimization**: Add description (150-160 chars) and relevant keywords
+7. **Testing**: Run `.\build.ps1 -Task Test` to validate sidebar links
+8. **Preview**: Use `.\build.ps1 -Task Server` to review locally before publishing
+
+### Adding New Authors or Tags
+- **Authors**: Add to `blog/authors.yml` with handle, name, title, url, image_url, socials
+- **Tags**: Add to `blog/tags.yml` with label, permalink, description
+- **Sync**: Run `.\build.ps1 -Task FrontMatterCMSSync` to update CMS choices files
+
+## Dependencies
+- **Node.js**: >=18.0 (managed via package.json engines)
+- **PowerShell**: 7+ (required by psakeFile.ps1)
+- **Package manager**: Yarn (locked version in packageManager field)
+- **PowerShell modules**: Auto-installed via PSDepend on bootstrap

.vscode/settings.json

@@ -1,8 +1,7 @@
 {
-  "frontMatter.dashboard.openOnStart": true,
   "files.trimTrailingWhitespace": true,
   "files.insertFinalNewline": true,
   "editor.insertSpaces": true,
   "editor.tabSize": 2,
   "powershell.codeFormatting.preset": "OTBS"
-}
+}

.vscode/tasks.json

@@ -54,5 +54,10 @@
         "isDefault": true
       }
     },
+    {
+      "label": "Bootstrap",
+      "type": "shell",
+      "command": "${cwd}/build.ps1 -Task Init -Bootstrap -Verbose"
+    },
   ]
 }

authors.choices.jsonc

@@ -0,0 +1,17 @@
+[
+  {
+    "_comment": "This file is auto-generated from blog/authors.yml via a psake task"
+  },
+  {
+    "url": "https://gilbertsanchez.com",
+    "title": "Core Contributor",
+    "image_url": "https://github.com/heyitsgilbert.png",
+    "name": "Gilbert Sanchez",
+    "socials": {
+      "linkedin": "gilbertsanchez",
+      "github": "HeyItsGilbert",
+      "x": "HeyItsGilbertS"
+    },
+    "handle": "heyitsgilbert"
+  }
+]

blog/2025-08-03-exciting-new-releases-you-cant-miss.md

@@ -0,0 +1,97 @@
+---
+title: New Releases & More!
+description: Discover the latest updates and releases in psake and PowerShellBuild that you won't want to miss!
+date: 2025-08-03T23:38:05.100Z
+slug: new-releases-and-more
+authors:
+  - heyitsgilbert
+tags:
+  - announcement
+  - release
+  - psake
+  - powershell
+  - build-automation
+keywords:
+  - psake
+  - PowerShellBuild
+  - build automation
+  - PowerShell
+  - release announcement
+  - CI/CD
+  - localization
+image: /img/social-card.png
+draft: false
+fmContentType: blog
+title_meta: August - New Releases and more!
+---
+
+It's been a while since our last update, and we've got some exciting news to
+share! In this post, we'll cover recent releases, welcome new team members, and
+highlight the various initiatives we're working on to make psake even better.
+
+<!-- truncate -->
+
+## Latest Versions
+
+Since launching this documentation site, we haven't been great about announcing
+new versions here. You could say we've been in stealth mode (though we're
+definitely not that cool).
+
+### psake
+
+Back in October, we released psake 4.9.1, and since then we've merged several
+pull requests, including some fantastic community contributions.
+
+Check out the
+[psake Changelog](https://github.com/psake/psake/blob/main/CHANGELOG.md) for all
+the details.
+
+The next release will introduce a new way to override the psake logging
+mechanism. This will allow teams to integrate additional logging frameworks or
+create improved CI/CD-specific workflows.
+
+### PowerShellBuild
+
+Just a few days ago, we updated PowerShellBuild - our collection of common tasks
+for psake and Invoke-Build - to support overriding task dependencies. We also
+added localization support (more on that below). This brings us to version 0.7.3
+as our latest release. Since version 0.6.2, we've seen 4.5k downloads, and we
+hope to keep improving the project based on your feedback.
+
+See the
+[PowerShellBuild Changelog](https://github.com/psake/PowerShellBuild/blob/main/CHANGELOG.md)
+for complete details.
+
+## Welcome Our Newest Team Members
+
+You may have noticed them working on and reviewing code in our repositories, but
+we'd like to formally welcome Joshua Hendricks and Trent Blackburn as new
+members of the psake core team!
+
+**Joshua** is our resident
+[MVP](https://mvp.microsoft.com/MVP/profile/f98b4f3e-12fd-40de-bdce-1467f04d430d)
+who's well-known for presenting at PowerShell + DevOps Global Summit on building
+beautiful docs and sending notifications. He's a developer at Milestone Systems
+where he maintains their PowerShell module.
+
+**Trent** currently develops PowerShell automations at Tesla, previously
+specialized in PowerShell at Amazon, and has also presented at the annual
+PowerShell + DevOps Global Summit.
+
+Both bring incredible expertise to the team, and we're excited to have them
+aboard! If you're interested in contributing to psake, please consider opening
+an issue or submitting a pull request—we'd love to hear from you.
+
+## Expanding Global Accessibility with Localization
+
+psake has long had the framework in place for supporting localization (l10n),
+but until now has only been available in English. One of our key goals is making
+psake as accessible as possible for users worldwide.
+
+To make community contributions easier, we've set up a
+[Crowdin project](http://crowdin.com/project/psake) that enables straightforward
+translation requests and suggestions.
+
+With the Crowdin project now live, we have a streamlined pipeline for
+introducing new localized versions. We'd love your help in making psake
+available in more languages - please consider contributing translations!

blog/authors.yml

@@ -1,4 +1,3 @@
-# https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#authors-file
 heyitsgilbert:
   name: Gilbert Sanchez
   title: Core Contributor

blog/tags.yml

@@ -1,19 +1,89 @@
-facebook:
-  label: Facebook
-  permalink: /facebook
-  description: Facebook tag description
-
-hello:
-  label: Hello
-  permalink: /hello
-  description: Hello tag description
-
-docusaurus:
-  label: Docusaurus
-  permalink: /docusaurus
-  description: Docusaurus tag description
-
-hola:
-  label: Hola
-  permalink: /hola
-  description: Hola tag description
+powershell:
+  label: PowerShell
+  permalink: /powershell
+  description: PowerShell scripting and automation content
+
+build-automation:
+  label: Build Automation
+  permalink: /build-automation
+  description: Automated build processes and continuous integration
+
+psake:
+  label: psake
+  permalink: /psake
+  description: psake build automation framework content
+
+ci-cd:
+  label: CI/CD
+  permalink: /ci-cd
+  description: Continuous Integration and Continuous Deployment
+
+testing:
+  label: Testing
+  permalink: /testing
+  description: Software testing strategies and tools
+
+deployment:
+  label: Deployment
+  permalink: /deployment
+  description: Application deployment and release management
+
+scripting:
+  label: Scripting
+  permalink: /scripting
+  description: Script development and automation techniques
+
+tutorial:
+  label: Tutorial
+  permalink: /tutorial
+  description: Step-by-step tutorials and guides
+
+getting-started:
+  label: Getting Started
+  permalink: /getting-started
+  description: Beginner-friendly content and setup guides
+
+advanced:
+  label: Advanced
+  permalink: /advanced
+  description: Advanced techniques and expert-level content
+
+best-practices:
+  label: Best Practices
+  permalink: /best-practices
+  description: Recommended approaches and industry standards
+
+tips:
+  label: Tips & Tricks
+  permalink: /tips
+  description: Helpful tips and useful tricks
+
+troubleshooting:
+  label: Troubleshooting
+  permalink: /troubleshooting
+  description: Problem-solving and debugging guides
+
+release:
+  label: Release
+  permalink: /release
+  description: Product releases and version announcements
+
+announcement:
+  label: Announcement
+  permalink: /announcement
+  description: Important announcements and updates
+
+msbuild:
+  label: MSBuild
+  permalink: /msbuild
+  description: Microsoft Build Engine integration
+
+dotnet:
+  label: .NET
+  permalink: /dotnet
+  description: .NET framework and .NET Core development
+
+visual-studio:
+  label: Visual Studio
+  permalink: /visual-studio
+  description: Visual Studio IDE integration and tools