Conversation
There was a problem hiding this comment.
Pull request overview
Migrates the documentation site from a simple GitHub Pages setup to a Docusaurus-based site, restructuring docs into About / Use / Extend / Reference, updating navigation, and adding CI checks + deployment workflow.
Changes:
- Introduces a Docusaurus site under
website/with sidebar/navigation configuration and themed homepage assets. - Restructures and updates
docs/content to match the new section model and fixes many internal links for Docusaurus/MDX. - Adds documentation auditing + GitHub Pages build/deploy workflows to keep docs consistent and deployable.
Reviewed changes
Copilot reviewed 57 out of 97 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| website/static/img/undraw_docusaurus_tree.svg | Adds static illustration asset for the site. |
| website/static/img/undraw_docusaurus_mountain.svg | Adds static illustration asset for the site. |
| website/static/img/logo.svg | Adds a logo SVG asset for the site. |
| website/static/img/favicon.ico | Adds favicon asset in static/img. |
| website/static/img/docusaurus.png | Adds an image asset in static/img. |
| website/static/.nojekyll | Disables Jekyll processing for GitHub Pages output. |
| website/src/pages/markdown-page.md | Adds example standalone markdown page. |
| website/src/pages/index.module.css | Adds homepage hero layout styling. |
| website/src/pages/index.js | Adds Docusaurus homepage with hero + CTA wiring. |
| website/src/css/custom.css | Adds theme CSS variables and minor component styling. |
| website/src/components/HomepageFeatures/styles.module.css | Adds homepage features grid styling. |
| website/src/components/HomepageFeatures/index.js | Adds homepage features component using static images. |
| website/sidebars.js | Defines the new About/Use/Extend/Reference sidebar model. |
| website/scripts/sync-assets.js | Adds script to sync docs/assets into website/static/assets. |
| website/package.json | Adds Docusaurus site dependencies and scripts (including asset sync). |
| website/docusaurus.config.js | Configures Docusaurus for GitHub Pages (repo baseUrl, plugins, theme). |
| website/README.md | Adds developer instructions for local Docusaurus workflow. |
| tools/Test-DocsConsistency.ps1 | Adds a docs audit tool (orphan/link/MDX-risk/long-page checks) for CI. |
| tools/Generate-IdleStepReference.ps1 | Updates step reference generator to sanitize help text for MDX safety. |
| tools/Generate-IdleCmdletReference.ps1 | Updates cmdlet reference generator to post-process output for MDX safety. |
| docs/use/workflows.md | Adds frontmatter and updates template-substitution documentation for MDX compatibility. |
| docs/use/steps.md | Adds frontmatter and updates links/MDX-sensitive tokens. |
| docs/use/quickstart.md | Adds a new Quick Start guide in the new docs structure. |
| docs/use/providers.md | Adds frontmatter and updates provider documentation links for new structure. |
| docs/use/plan-export.md | Adds a new user guide page for plan export. |
| docs/use/intro.md | Adds a new Use section landing page. |
| docs/use/installation.md | Adds frontmatter and updates links to the new structure. |
| docs/use/configuration.md | Adds frontmatter and updates related links to the new structure. |
| docs/reference/steps.md | Updates generated step reference for MDX-safe tokens. |
| docs/reference/specs/plan-export.md | Updates spec intro/structure and minor formatting. |
| docs/reference/providers/provider-entraID.md | Updates “See also” links to new paths. |
| docs/reference/providers/provider-ad.md | Updates examples/links for MDX safety and new structure. |
| docs/reference/intro.md | Adds a new Reference section landing page. |
| docs/reference/cmdlets/Test-IdleWorkflow.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/cmdlets/New-IdlePlan.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/cmdlets/New-IdleLifecycleRequest.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/cmdlets/New-IdleAuthSession.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/cmdlets/Invoke-IdlePlan.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/cmdlets/Export-IdlePlan.md | Updates generated cmdlet docs for MDX-safe tokens/placeholders. |
| docs/reference/capabilities.md | Adds a new capabilities reference document. |
| docs/overview/concept.md | Removes old docsify-era overview page. |
| docs/index.md | Updates docs “map” page to new structure and website link. |
| docs/index.html | Removes docsify HTML entrypoint. |
| docs/getting-started/quickstart.md | Removes old quickstart page (replaced by new structure). |
| docs/extend/steps.md | Updates links/related section for new structure. |
| docs/extend/providers.md | Adds frontmatter and updates content/links for new structure. |
| docs/extend/intro.md | Adds a new Extend section landing page. |
| docs/extend/extensibility.md | Adds frontmatter and updates links for new structure/capabilities reference. |
| docs/extend/events.md | Adds frontmatter and updates links for new structure. |
| docs/develop/testing.md | Adds documentation audit instructions. |
| docs/develop/releases.md | Adds frontmatter and updates installation guide link. |
| docs/advanced/provider-capabilities.md | Removes old provider-capabilities page (replaced by capabilities reference). |
| docs/about/security.md | Adds frontmatter and updates for new About section. |
| docs/about/intro.md | Adds a new About landing/intro document. |
| docs/about/concepts.md | Adds a new Concepts document (replacing old overview). |
| docs/about/architecture.md | Adds frontmatter and updates links to new spec/capabilities pages. |
| docs/_sidebar.md | Removes docsify sidebar file. |
| docs/_navbar.md | Removes docsify navbar file. |
| docs/_config.yml | Removes Jekyll config for old GH Pages docs. |
| README.md | Updates repo README links to new docs structure and website. |
| CONTRIBUTING.md | Updates key docs links after restructuring. |
| .gitignore | Adds ignores relevant to Node/Docusaurus and docs artifacts. |
| .github/workflows/pages.yml | Adds docs build + deploy workflow for GitHub Pages (including docs audit). |
| .github/workflows/ci.yml | Excludes website/** from main CI workflow triggers to reduce noise. |
Comments suppressed due to low confidence (5)
docs/about/architecture.md:3
- Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). With the current key, the sidebar label may be ignored. Rename this field tosidebar_label.
docs/use/workflows.md:146 - These workflow examples show template placeholders with extra backticks/backslashes inside the PowerShell string literals (e.g.
'`\{\{Request.Input...\}\}`'). That is not the actual IdLE template syntax and would be copied incorrectly by readers. Inside fenced code blocks you don’t need MDX escaping—use the real{{...}}placeholder strings, and keep MDX-escaping only in normal paragraph text/inline code.
docs/use/workflows.md:208 - The "Escaping" example includes backticks around
{{...}}inside the single-quoted PowerShell string, which changes the literal content and is not representative of how to escape{{in workflow strings. Since this is inside a fenced code block, keep the example as the actual workflow string syntax (no extra backticks) and explain escaping in surrounding prose if needed.
docs/about/security.md:3 - Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). With the current key, the sidebar label may be ignored. Rename this field tosidebar_label.
docs/develop/releases.md:3 - Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). With the current key, the sidebar label may be ignored. Rename this field tosidebar_label.
| $plan = New-IdlePlan -WorkflowPath './workflows/joiner.json' -IdentityId 'jdoe' | ||
| Export-IdlePlan -Plan $plan -Path './artifacts/joiner.plan.json' |
There was a problem hiding this comment.
This example uses -WorkflowPath './workflows/joiner.json' -IdentityId 'jdoe', but New-IdlePlan (per implementation) takes -WorkflowPath for a PSD1 workflow and requires a -Request object (from New-IdleLifecycleRequest). Update the example to match the actual cmdlet parameters and file type.
There was a problem hiding this comment.
@copilot open a new pull request to apply changes based on this feedback
|
@blindzero I've opened a new pull request, #122, to work on those changes. Once the pull request is ready, I'll request review from you. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 57 out of 97 changed files in this pull request and generated 3 comments.
Comments suppressed due to low confidence (5)
website/sidebars.js:105
- This file uses
export default sidebars;(ESM). However,tools/Test-DocsConsistency.ps1loadswebsite/sidebars.jsvia Noderequire(...), which will fail to parse ESM syntax under the currentwebsite/package.json(notype: module). Convert this file to CommonJS (module.exports = sidebars) or update the audit script to load ESM via dynamicimport()and handle the.defaultexport.
docs/use/workflows.md:208 - The “Escaping” example says to use
\{{for a literal{{, but the sample string uses\`{{/ backticks, which changes the literal value and no longer matches the described escape mechanism. Update the example to show the actual\{{sequence (and keep template placeholders unmodified) so it reflects real workflow syntax.
docs/about/security.md:4 - Docusaurus front matter uses
sidebar_label(singular).sidebar_labelsis not a recognized key, so this page’s sidebar label won’t be applied. Renamesidebar_labelstosidebar_label.
docs/about/architecture.md:4 - Docusaurus front matter uses
sidebar_label(singular).sidebar_labelsis not a recognized key, so this page’s sidebar label won’t be applied. Renamesidebar_labelstosidebar_label.
docs/develop/releases.md:4 - Docusaurus front matter uses
sidebar_label(singular).sidebar_labelsis not a recognized key, so this page’s sidebar label won’t be applied. Renamesidebar_labelstosidebar_label.
| ```powershell | ||
| # Example only. Adjust parameters to your environment. | ||
| $plan = New-IdlePlan -WorkflowPath './workflows/joiner.json' -IdentityId 'jdoe' | ||
| Export-IdlePlan -Plan $plan -Path './artifacts/joiner.plan.json' | ||
| ``` |
There was a problem hiding this comment.
The example uses New-IdlePlan -WorkflowPath './workflows/joiner.json' -IdentityId 'jdoe', but New-IdlePlan’s documented syntax requires -Request and workflows are .psd1 in this repo. Update the sample to build a request and pass it to New-IdlePlan, and reference a .psd1 workflow path.
There was a problem hiding this comment.
@copilot open a new pull request to apply changes based on this feedback
|
@blindzero I've opened a new pull request, #123, to work on those changes. Once the pull request is ready, I'll request review from you. |
Co-authored-by: blindzero <13959569+blindzero@users.noreply.github.com>
Fix plan-export.md example to use correct New-IdlePlan syntax
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 57 out of 97 changed files in this pull request and generated 7 comments.
Comments suppressed due to low confidence (9)
docs/about/architecture.md:92
Invoke-IdlePlan -EventSink <object>is already in inline code, so HTML-escaping<object>is unnecessary and will likely render literally as<object>. Use<object>inside the backticks for readability and copy/paste.
docs/use/workflows.md:145- In this workflow example, the template placeholders are wrapped in backticks/backslashes inside the string literal (e.g.
'`\{\{Request.Input.UserPrincipalName\}\}`'). IdLE’s resolver expects literal{{...}}inside the string (and uses\{{only to escape a literal{{), so the current example won’t resolve correctly when copied into a workflow.
docs/about/architecture.md:4 - Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). With the current key, the sidebar label override will be ignored.
docs/about/security.md:4 - Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). With the current key, the sidebar label override will be ignored.
docs/use/steps.md:70 Invoke-IdlePlan -EventSink <object>is already in inline code, so HTML-escaping<object>is unnecessary and will likely render literally as<object>. Use<object>inside the backticks.
docs/use/workflows.md:208- The escaping example uses
\{{and shows a resolved output containing backticks. The actual escape sequence implemented by IdLE is{{→{{` (no backticks), so this snippet/output doesn’t match runtime behavior.
docs/use/workflows.md:154 - This message template example includes escaped braces/backticks inside the quoted string. For a real workflow, it should use literal
{{Request.Input.DisplayName}}/{{Request.Input.UserPrincipalName}}so IdLE can resolve the placeholders.
docs/develop/releases.md:4 - Frontmatter uses
sidebar_labels, but Docusaurus expectssidebar_label(singular). As written, the custom sidebar label will be ignored and it will fall back to the title.
docs/develop/releases.md:100 vMAJOR.MINOR.PATCH-<label>is inside inline code already, so escaping<label>to an HTML entity will likely render literally as<label>(hurting readability/copy-paste). Use<label>inside the backticks instead.
|
|
||
| **Error:** `Identity with <identifier> not found` | ||
| **Error:** `Identity with <identifier> not found` | ||
|
|
There was a problem hiding this comment.
**Error:** Identity with <identifier> not found`` is already in inline code, so escaping <identifier> is unnecessary and will likely render literally as `<identifier>`. Use `` inside the backticks for readability.
| With = @{ | ||
| IdentityKey = 'user@target.com' | ||
| Attributes = @{ ... } | ||
| Attributes = @\{ ... \} | ||
| Provider = 'TargetAD' |
There was a problem hiding this comment.
This code example is inside a fenced block, so escaping the hashtable literal as @\{ ... \} is unnecessary and breaks copy/paste (PowerShell requires @{ ... }). Consider reverting this line to a normal hashtable literal.
|
|
||
| # IdentityLifecycleEngine (IdLE) | ||
|
|
||
|  |
There was a problem hiding this comment.
The logo path points to /assets/idle_logo_flat_white_text_small.png, but the docs asset structure is under /assets/logos/... (see docs/assets/logos). Keeping the old path relies on stale files under website/static/assets and may break after a clean sync; update it to /assets/logos/idle_logo_flat_white_text_small.png.
|  | |
|  |
| <Layout | ||
| title={`Hello from ${siteConfig.title}`} | ||
| description="Description will go into a meta tag in <head />"> | ||
| <HomepageHeader /> |
There was a problem hiding this comment.
Layout still uses the default template metadata (title={\Hello from ...`}and a placeholder description). This will ship as the homepage<title>/meta description unless overridden by Docusaurus defaults; update to a meaningful site title/description (or omit these props to use siteConfig`).
| $script = @" | ||
| const path = require('path'); | ||
| const sbPath = process.argv[1]; | ||
| const sb = require(path.resolve(sbPath)); | ||
|
|
There was a problem hiding this comment.
Get-SidebarDocIds uses require() to load website/sidebars.js, but that file is authored as an ES module (export default ...). In a plain Node.js context this will throw (e.g., Unexpected token 'export'), causing the docs consistency audit (and Pages workflow) to fail. Consider either switching website/sidebars.js to CommonJS (module.exports = sidebars) or updating the Node snippet to use dynamic import() and read the default export.
| const repoRoot = path.resolve(__dirname, '..', '..'); | ||
| const sourceRoot = path.join(repoRoot, 'docs', 'assets'); | ||
| const targetRoot = path.join(repoRoot, 'website', 'static', 'assets'); | ||
|
|
||
| function copyRecursive(srcDir, dstDir) { |
There was a problem hiding this comment.
sync-assets.js only copies from docs/assets into website/static/assets and does not remove files that were deleted/renamed at the source. Over time this can leave stale assets behind and make docs accidentally depend on old paths; consider pruning/cleaning the destination before copying.
| function Write-GitHubAnnotation { | ||
| [CmdletBinding()] | ||
| param( | ||
| [Parameter(Mandatory)] | ||
| [ValidateSet('error', 'warning', 'notice')] | ||
| [string] $Level, | ||
|
|
||
| [Parameter(Mandatory)] | ||
| [ValidateNotNullOrEmpty()] | ||
| [string] $Message, | ||
|
|
||
| [Parameter()] | ||
| [AllowEmptyString()] | ||
| [string] $File, | ||
|
|
||
| [Parameter()] | ||
| [int] $Line = 0 | ||
| ) | ||
|
|
||
| if (-not (Get-IsGitHubActions)) { return } | ||
|
|
||
| $parts = @() | ||
| if (-not [string]::IsNullOrWhiteSpace($File)) { | ||
| $parts += "file=$File" | ||
| } | ||
| if ($Line -gt 0) { | ||
| $parts += "line=$Line" | ||
| } | ||
|
|
||
| if ($parts.Count -gt 0) { | ||
| Write-Output ("::{0} {1}::{2}" -f $Level, ($parts -join ','), $Message) | ||
| } | ||
| else { | ||
| Write-Output ("::{0}::{1}" -f $Level, $Message) | ||
| } |
There was a problem hiding this comment.
Write-GitHubAnnotation builds GitHub Actions workflow command lines using unescaped Message values that can contain newlines from untrusted documentation content (e.g., malformed Markdown link targets), allowing an attacker to inject additional :: commands when this script runs in CI. On GitHub Actions, this can be exploited by crafting a doc link whose target spans a newline followed by a workflow command (such as ::set-output or other control commands), which the runner will execute as a separate command. To fix this, sanitize or escape annotation fields before emitting them (at minimum stripping or encoding newlines and other command-delimiting characters from Message and other dynamic values, or avoiding workflow-command syntax for untrusted text).
Summary
Prepare the Docusaurus docs site for GitHub Pages deployment by restructuring docs into the new section model (About / Use / Extend / Reference), updating navigation, fixing links, and ensuring MDX compatibility (including generator-safe output).
Motivation
We needed a clean, predictable documentation structure that matches the intended audiences (admins/users vs extenders vs reference), avoids “hidden” pages, and builds reliably in Docusaurus without MDX compilation errors. In addition, generated docs must remain correct after regeneration (no manual-only fixes).
Type of Change
Please select the relevant option:
Changes
website/sidebars.jsso published docs are fully reachable (no orphaned pages).docs.exclude)Testing
Describe how this change was tested.
How to test & review
pwsh .\tools\DocsAudit.ps1 -DocsPath .\docs -WebsitePath .\websiteOrphanDocIds: [],LinkIssues: []cd websitenpm cinpm run buildChecklist