# MicrosoftDocs/PowerShell-Docs: what the official documentation repository actually contains

> The PowerShell-Docs repository is the source of the cmdlet reference and conceptual articles published on learn.microsoft.com. It is a documentation build system, not a PowerShell distribution, and that distinction decides who should clone it.

**MicrosoftDocs/PowerShell-Docs** — The official PowerShell documentation sources

- Repository: https://github.com/MicrosoftDocs/PowerShell-Docs
- Website: https://learn.microsoft.com/powershell
- Stars: 2,559 · Forks: 1,724
- Language: PowerShell
- License: NOASSERTION
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoftdocs-powershell-docs

## PowerShell-Docs is documentation source, not a PowerShell download

The repository holds the Markdown that becomes the PowerShell pages on learn.microsoft.com. The README is explicit that the reference content in the numbered folders is used both for the website and for the updatable help that PowerShell itself consumes, while the articles under docs-conceptual are published to the website only. That single sentence is the most important design fact in the project, because it means a change to a cmdlet page has a wider blast radius than a change to a tutorial.

The audience is narrow and identifiable. Documentation contributors, writers who maintain cmdlet reference pages, and engineers who need to read the source of a page rather than the rendered HTML. The topics list includes hacktoberfest, which signals that drive-by contributions are expected and tolerated. If you arrived looking for an installer, the README points to the learn.microsoft.com homepage instead, and no release artifacts are described in the repository metadata.

## How the reference, redir and tools folders fit together

The repository layout separates five kinds of content. The reference folder contains cmdlet reference for PowerShell 5.1, 7.4, 7.5, 7.6 and 7.7, each in its own numbered directory, plus breadcrumb navigation, includes, version mapping configuration, media and the Module Browser page source. The redir folder holds URL redirection mapping files, which is how old documentation URLs keep resolving after a page moves. The tools folder holds the build system scripts, tests contains Pester tests for build validation, and assets holds downloadable files that documentation links to.

That split matters when you plan a change. A new cmdlet page goes into every version folder where the cmdlet exists, because the version mapping configuration decides which page a given PowerShell version surfaces. A moved page needs an entry in redir, otherwise the old URL breaks. The presence of a dedicated mapping folder alongside the numbered versions suggests the project treats version routing as configuration rather than as convention, which is a reasonable choice for documentation that has to stay accurate across five parallel releases.

## Cloning PowerShell-Docs and validating a change locally

The README does not give install commands. It points contributors at the contributor's guide at aka.ms/PSDocsContributor for detailed instructions, suggested tools, and style and formatting requirements, and it asks that the Issue and Pull Request templates be used. What can be confirmed from the repository listing is that validation is scripted: build.ps1 sits at the top level, Pester tests live in tests, and the root contains lint configuration in .markdownlint.yaml, .markdownlint-cli2.yaml and .vale.ini.

A first real use is therefore a local lint pass rather than a documentation build. Clone the repository and run the Markdown linter against a file you edited, using the configuration the repository already ships:

```bash
git clone https://github.com/MicrosoftDocs/PowerShell-Docs.git
cd PowerShell-Docs
npx markdownlint-cli2 --config .markdownlint-cli2.yaml "reference/**/*.md"
```

The reader should expect the linter to report style violations drawn from the repository's own ruleset, not from the default Markdown rules. Vale is configured separately through .vale.ini for prose style, and build.ps1 is the entry point the project uses for its own build steps. The README does not document what build.ps1 does when run without arguments, so treat it as a script to read before executing rather than one to run blind.

## Dual licensing and the Contribution License Agreement gate

The README states there are two license files: the MIT License in LICENSE-CODE.md applies to the code in the repository, and the Creative Commons license in LICENSE.md applies to the documentation. The repository metadata reports the license as NOASSERTION, which is consistent with a repository that carries two license files rather than one SPDX identifier at the root. If you intend to reuse the prose, read LICENSE.md rather than assuming the MIT terms cover it, and read LICENSE-CODE.md for the scripts in tools and tests. This is a description of what the files say, not legal advice.

The contribution path has a hard gate. The README states that a pull request cannot be accepted until the contributor signs the Contribution License Agreement at cla.microsoft.com, and describes it as a one-time requirement. For a one-line typo fix in a cmdlet page, that is a real cost, and it is the main reason casual contributors stop at filing an issue instead. The presence of Issue and Pull Request templates reinforces that the project prefers structured reports over unstructured patches.

## Where PowerShell-Docs is the wrong repository to touch

The repository contains documentation, and the README does not describe any mechanism for changing PowerShell's behaviour. If a cmdlet returns the wrong value, editing its reference page will not fix it; the page describes what the shipped product does. Contributors who file documentation pull requests for product bugs are pushing against the wrong repository, and the contributor's guide is the place the project routes that distinction.

There is a second boundary. The conceptual articles under docs-conceptual are published only to the website, so they do not reach the updatable help that PowerShell downloads. If your goal is to change what `Get-Help` shows for a cmdlet, the numbered reference folders are the only place that matters, and the README says so directly. Editing a conceptual article to improve in-console help is a dead end. A third constraint is versioning: five reference versions are maintained in parallel, so a single edit is rarely a single edit.

## PowerShell-Docs compared with the platyPS workflow

A common alternative for teams that ship their own modules is platyPS, which generates Markdown cmdlet reference from a compiled module and can package that Markdown back into updatable help. The difference in approach is the direction of truth. PowerShell-Docs is hand-authored source that the build system renders and that CabGen packages into updatable help, with a CI status badge in the README tracking that packaging pipeline. platyPS treats the module as the source and the Markdown as generated output.

That makes platyPS the better fit when your cmdlets change often and you want the reference to follow the code. It makes PowerShell-Docs the better fit when the prose is the product and the cmdlet surface is stable across a long support window, which is the situation for PowerShell itself. The trade-off is maintenance load: hand-authored reference across five versions means every parameter addition is multiplied by the number of version folders that include the cmdlet.

## Upgrade cost and what to verify before your first pull request

There are no releases in the repository metadata, so there is no version number to track and no changelog to read before upgrading. The last push was on 2026-09-24, four days before the date used for this review, so the main branch moves often and a long-lived fork will drift quickly. The practical upgrade cost is rebasing your branch rather than migrating an API.

Before opening a pull request, verify three things against the repository itself. Confirm the Contribution License Agreement link in the README resolves, since the README makes signing it a precondition. Confirm which numbered reference folders contain the cmdlet you are documenting, because omitting a version leaves that release's help stale. Confirm whether your change needs a redir entry, because moving a published page without one breaks the old URL. The repository does not document a rollback procedure for a merged documentation change, so treat the pull request review as the only checkpoint you get.

## Conclusion

Adopt this repository if you are correcting a cmdlet page, adding a conceptual article, or building tooling against the versioned reference folders for 5.1 through 7.7. Do not clone it to get a PowerShell binary, and do not expect a stable API from the tools directory. Before contributing, read CONTRIBUTING.md and confirm the Contribution License Agreement link resolves, since the README states the CLA is required before a pull request can be accepted. Before writing, check whether your page belongs in reference or docs-conceptual, because only the numbered reference folders feed the updatable help that ships with PowerShell.

## FAQ

### What is PowerShell used for?

The repository is documentation rather than the product, so it does not answer this directly. What it does show is the scope of the documented surface: cmdlet reference maintained in parallel for PowerShell 5.1, 7.4, 7.5, 7.6 and 7.7, plus conceptual articles published to learn.microsoft.com.

### How to use the PowerShell command?

The cmdlet reference for each supported version lives in the numbered folders under reference, and the README notes that this content also becomes the updatable help used by PowerShell. The repository itself gives no usage walkthrough beyond pointing to the contributor's guide for documentation work.

### Is PowerShell still relevant?

The repository metadata shows the last push was on 2026-09-24, and the reference folder covers PowerShell 7.7 alongside 5.1 and the intermediate 7.x releases. That version spread is the evidence available here; the README makes no claim about adoption.

## Sources

- [Issues](https://github.com/MicrosoftDocs/PowerShell-Docs/issues)
- [MicrosoftDocs/PowerShell-Docs on GitHub](https://github.com/MicrosoftDocs/PowerShell-Docs)
- [Project website](https://learn.microsoft.com/powershell)
- [README](https://github.com/MicrosoftDocs/PowerShell-Docs/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoftdocs-powershell-docs