diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 000000000..dfc70edc0 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,15 @@ +# PowerShell.org Website + +The community website for PowerShell.org, built with Hugo and Tailwind CSS. Hosts +podcasts, summit info, learning articles, community resources, and dedicated landing +pages for the open-source Modules that PowerShell.org stewards. + +## Language + +**Module**: +A PowerShell module that PowerShell.org stewards as an open-source project (e.g. +Plaster, PSDepend), given a dedicated landing page under `/modules/`. Capitalized +and used as a site section, "Module" means specifically these org-stewarded projects +— not the generic sense of "any PowerShell module you `Install-Module`", which is the +subject of the site as a whole. +_Avoid (for this concept)_: project, tool, package diff --git a/archetypes/modules.md b/archetypes/modules.md new file mode 100644 index 000000000..3192ff379 --- /dev/null +++ b/archetypes/modules.md @@ -0,0 +1,23 @@ +--- +title: '{{ replace .File.ContentBaseName "-" " " | title }}' +description: "" +layout: "module" +icon: "fas fa-cube" +weight: 50 +repo: "" +gallery: "" +docs: "" +install: + - label: "PowerShell 7+" + command: "" + - label: "PowerShell 5.1" + command: "" +features: + - icon: "fas fa-star" + title: "" + body: "" +cmdlets: + - name: "" + description: "" +draft: true +--- diff --git a/content/modules/_index.md b/content/modules/_index.md new file mode 100644 index 000000000..e04c866c9 --- /dev/null +++ b/content/modules/_index.md @@ -0,0 +1,7 @@ +--- +title: "Modules" +description: "Open-source PowerShell modules stewarded by the PowerShell.org community." +--- + +Tools built and maintained by the PowerShell.org community. Install them from the +PowerShell Gallery and dig into the source on GitHub. diff --git a/content/plaster/_index.md b/content/modules/plaster/_index.md similarity index 73% rename from content/plaster/_index.md rename to content/modules/plaster/_index.md index f02690ddf..3956a5b1d 100644 --- a/content/plaster/_index.md +++ b/content/modules/plaster/_index.md @@ -2,4 +2,8 @@ title: "Plaster" description: "The template engine for PowerShell. Scaffold projects, modules, and files with customizable templates in XML or JSON." layout: "plaster" +icon: "fas fa-layer-group" +weight: 10 +aliases: + - "/plaster/" --- diff --git a/content/modules/psdepend/_index.md b/content/modules/psdepend/_index.md new file mode 100644 index 000000000..4c4d111ad --- /dev/null +++ b/content/modules/psdepend/_index.md @@ -0,0 +1,73 @@ +--- +title: "PSDepend" +description: "A PowerShell dependency handler. Declare your dependencies in a .psd1 file and let Invoke-PSDepend resolve, install, import, and test them." +layout: "module" +icon: "fas fa-sitemap" +logo: "/images/modules/psdepend.svg" +weight: 20 +repo: "https://github.com/PowerShellOrg/PSDepend" +gallery: "https://www.powershellgallery.com/packages/PSDepend" +docs: "https://github.com/PowerShellOrg/PSDepend/blob/main/docs/en-US/about_PSDepend.help.md" +install: + - label: "PowerShell 7+" + command: "Install-PSResource PSDepend" + - label: "PowerShell 5.1" + command: "Install-Module PSDepend" +features: + - icon: "fas fa-file-code" + title: "Declarative DependencyFiles" + body: "Declare every Dependency in a simple .psd1 file. Invoke-PSDepend finds your *.depend.psd1 and requirements.psd1 files automatically — think pip install -r or bundle install for PowerShell." + - icon: "fas fa-plug" + title: "Pluggable DependencyTypes" + body: "Each Dependency picks a DependencyType — PSGalleryModule, Git, Chocolatey, FileDownload and more — that selects the DependencyScript handling it. Register your own to extend PSDepend." + - icon: "fas fa-list-check" + title: "Install, Test, or Import" + body: "Run a DependencyFile with any combination of the Install, Test, and Import PSDependActions — verify an environment in CI, or hydrate one from scratch." + - icon: "fas fa-tags" + title: "Tag-based selection" + body: "Tag your Dependencies and pass -Tags to Invoke-PSDepend to resolve just the subset you need for a given task or pipeline stage." + - icon: "fas fa-diagram-project" + title: "Ordered Prerequisites" + body: "Express ordering constraints between Dependencies with DependsOn. PSDepend resolves them into topological order before anything is installed." + - icon: "fas fa-bullseye" + title: "Flexible Target" + body: "Send a Dependency to a scope (CurrentUser, AllUsers) or any filesystem path via Target. The DependencyScript branches on whichever you give it." +cmdlets: + - name: "Invoke-PSDepend" + description: "The main entry point. Resolves a DependencyFile and installs, tests, and/or imports its Dependencies." + - name: "Get-Dependency" + description: "Parse a DependencyFile into typed Dependency objects without acting on them — handy for inspection and debugging." + - name: "Get-PSDependType" + description: "List the registered DependencyTypes and the DependencyScript each one maps to." + - name: "Get-PSDependScript" + description: "Resolve the DependencyScript that will handle a given DependencyType." + - name: "Install-Dependency" + description: "Run only the Install PSDependAction for a Dependency." + - name: "Test-Dependency" + description: "Run only the Test PSDependAction to check whether a Dependency is already satisfied." +--- + +## Declare your dependencies + +Store your Dependencies in a PowerShell data file named `*.depend.psd1` or +`requirements.psd1`. The simplest form maps a module name to a version: + +{{< terminal title="requirements.psd1" lang="powershell" >}} +@{ + psake = 'latest' + Pester = 'latest' + BuildHelpers = '0.0.20' + PSDeploy = '0.1.21' +} +{{< /terminal >}} + +Then resolve everything in one call: + +{{< terminal title="PowerShell" lang="powershell" >}} +Import-Module PSDepend +Invoke-PSDepend -Path .\requirements.psd1 +{{< /terminal >}} + +Need more control? Expand any entry into a full Dependency to set its +`DependencyType`, `Target`, `Tags`, or `DependsOn` ordering — and add a +`PSDependOptions` block to apply defaults across the whole DependencyFile. diff --git a/docs/adr/0001-module-landing-pages.md b/docs/adr/0001-module-landing-pages.md new file mode 100644 index 000000000..f40d42270 --- /dev/null +++ b/docs/adr/0001-module-landing-pages.md @@ -0,0 +1,32 @@ +# Module landing pages: hybrid layout under a `/modules/` section + +We host dedicated landing pages for the open-source PowerShell modules PowerShell.org +stewards (see [[Module]] in `CONTEXT.md`). Plaster's page is a hand-authored, ~430-line +bespoke Hugo layout. To add more modules (PSDepend first) without copy-pasting that per +module, we adopt a **hybrid**: a generic, front-matter-driven `module` layout is the +default for new modules, and the standard Hugo `layout:` key is an escape hatch so a +flagship module can keep a bespoke page (Plaster stays on `_default/plaster.html`). + +The modules live under a `/modules/` section with a card-grid index (built by +`layouts/modules/list.html` ranging over the child pages, mirroring the existing +`community` list). A single "Modules" item replaces "Plaster" in the main nav. Plaster +moves from `/plaster/` to `/modules/plaster/` with `aliases: ["/plaster/"]` to preserve +the published URL. + +## Considered options + +- **Bespoke per module** — rejected: ~430 lines of duplicated, drifting HTML per module. +- **Generic only** (convert Plaster too) — rejected: loses Plaster's bespoke showcase + (ASCII hero, JSON-vs-XML comparison) for a lowest-common-denominator template. +- **Hybrid** — chosen: cheap to add modules, expressive where it earns its keep. + +We named the section **"Module"** despite the collision with PowerShell's generic sense +of the word; `CONTEXT.md` carries the disambiguation. + +## Consequences + +- Every module page **must** set `layout:` (`module` or a bespoke name). Module pages are + branch bundles under `modules/`, so without an explicit layout they would fall through + to the section's `list.html`. The `modules` archetype bakes the layout key in. +- Cmdlet references on generic pages are a curated 3–6 command highlight in front matter, + not an ingestion of each module's platyPS docs — avoids cross-repo build coupling. diff --git a/hugo.yaml b/hugo.yaml index 8b36b748b..562736c10 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -48,9 +48,13 @@ menu: weight: 50 params: hasChildren: true - - name: "Plaster" - url: "/plaster/" + childMenu: community + - name: "Modules" + url: "/modules/" weight: 60 + params: + hasChildren: true + childMenu: modules community: - name: "Learning" url: "/learning/" @@ -83,6 +87,19 @@ menu: params: icon: "fab fa-discord" description: "Searchable archive of conversations from our Discord server." + modules: + - name: "Plaster" + url: "/modules/plaster/" + weight: 10 + params: + icon: "fas fa-layer-group" + description: "The template engine for PowerShell — scaffold projects, modules, and files." + - name: "PSDepend" + url: "/modules/psdepend/" + weight: 20 + params: + icon: "fas fa-sitemap" + description: "Declarative PowerShell dependency handler driven by a .psd1 file." # Site parameters params: diff --git a/static/images/modules/psdepend.svg b/static/images/modules/psdepend.svg new file mode 100644 index 000000000..a431f736e --- /dev/null +++ b/static/images/modules/psdepend.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/themes/powershell-community/layouts/_default/baseof.html b/themes/powershell-community/layouts/_default/baseof.html index b5fb6be7c..a925c91fe 100644 --- a/themes/powershell-community/layouts/_default/baseof.html +++ b/themes/powershell-community/layouts/_default/baseof.html @@ -80,6 +80,10 @@ font-family: 'Cascadia Code', 'Consolas', monospace; } + /* Neutralize .prose pre styling inside the terminal shortcode so the + terminal chrome renders flush; Prism handles token colors. */ + .ps-terminal pre { background: transparent; color: #ccc; margin: 0; border-radius: 0; padding: 1.25rem; overflow-x: auto; } + .hero-pattern { background: linear-gradient(135deg, #0078D4 0%, #00BCF2 100%); position: relative; diff --git a/themes/powershell-community/layouts/_default/module.html b/themes/powershell-community/layouts/_default/module.html new file mode 100644 index 000000000..eb6290d3c --- /dev/null +++ b/themes/powershell-community/layouts/_default/module.html @@ -0,0 +1,138 @@ +{{ define "main" }} + + +
+
+
+ {{ with .Params.logo }} +
+ + {{ $.Title }} logo + +
+ {{ else }}{{ with .Params.icon }} +
+ +
+ {{ end }}{{ end }} +

{{ .Title }}

+ {{ with .Params.description }} +

{{ . }}

+ {{ end }} +
+ {{ with .Params.repo }} + + View Source + + {{ end }} + {{ if .Params.install }} + + Install + + {{ end }} +
+
+
+
+ + +{{ with .Params.install }} +
+
+ {{ range . }} +
+
+
+
+
+
+
+ {{ with .label }}{{ . }}{{ else }}PowerShell{{ end }} +
+ {{ .command }} +
+ {{ end }} +
+
+{{ end }} + + +{{ with .Params.features }} +
+
+
+ {{ range . }} +
+
+ +
+

{{ .title }}

+

{{ .body }}

+
+ {{ end }} +
+
+
+{{ end }} + + +{{ with .Content }} +
+
+
{{ . }}
+
+
+{{ end }} + + +{{ with .Params.cmdlets }} +
+
+
+

Commands

+

The commands you'll reach for most.

+
+
+ {{ range . }} +
+
+ {{ .name }} +
+

{{ .description }}

+
+ {{ end }} +
+
+
+{{ end }} + + +
+
+

Get started with {{ .Title }}

+
+ {{ with .Params.gallery }} + + PowerShell Gallery + + {{ end }} + {{ with .Params.repo }} + + View Source + + {{ end }} + {{ with .Params.docs }} + + Documentation + + {{ end }} +
+
+
+ +{{ end }} diff --git a/themes/powershell-community/layouts/_shortcodes/terminal.html b/themes/powershell-community/layouts/_shortcodes/terminal.html new file mode 100644 index 000000000..b16e20b0e --- /dev/null +++ b/themes/powershell-community/layouts/_shortcodes/terminal.html @@ -0,0 +1,20 @@ +{{- /* Reusable terminal-chrome code block. Matches the styled blocks on the Plaster page. + Usage: + {{< terminal title="requirements.psd1" lang="powershell" >}} + @{ psake = 'latest' } + {{< /terminal >}} + Highlighting is handled client-side by Prism via the language-* class. */ -}} +{{- $lang := .Get "lang" | default "powershell" -}} +{{- $title := .Get "title" | default "PowerShell" -}} +{{- $code := trim .Inner "\n" -}} +
+
+
+
+
+
+
+ {{ $title }} +
+ 
{{ $code }}
+
diff --git a/themes/powershell-community/layouts/modules/list.html b/themes/powershell-community/layouts/modules/list.html new file mode 100644 index 000000000..ec2e1815e --- /dev/null +++ b/themes/powershell-community/layouts/modules/list.html @@ -0,0 +1,47 @@ +{{ define "main" }} + + +
+
+

{{ .Title }}

+ {{ if .Params.description }} +

{{ .Params.description }}

+ {{ end }} +
+
+ + +
+
+ {{ with .Content }} +
{{ . }}
+ {{ end }} + + +
+ {{ range .Pages.ByWeight }} + {{ $title := .Title }} + +
+
+ {{ with .Params.logo }} + {{ $title }} logo + {{ else }} + + {{ end }} +
+

+ {{ .Title }} +

+
+ {{ with .Params.description }} +

{{ . }}

+ {{ end }} + + {{ end }} +
+
+
+ +{{ end }} diff --git a/themes/powershell-community/layouts/partials/header.html b/themes/powershell-community/layouts/partials/header.html index 33c00a176..0d27b1876 100644 --- a/themes/powershell-community/layouts/partials/header.html +++ b/themes/powershell-community/layouts/partials/header.html @@ -16,7 +16,7 @@

PowerShell.org