From 84328dc5c69c10a43390b9f64afd2d5951eca52c Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Sun, 4 Oct 2026 14:11:59 +0200 Subject: [PATCH] docs: keep the documentation on GitHub and retire the wiki - Remove the Read the Docs and MkDocs configuration (.readthedocs.yml, mkdocs.yml, Docs/requirements.txt). The Read the Docs project belongs to a third party and points to a fork that no longer exists. - Rename Docs/index.md to Docs/README.md, so that GitHub shows the overview when you open the Docs folder, and link the changelog and the license relatively. - Move the version history and the installation steps from the wiki into Docs/Version-History.md and Docs/README.md. Add the notes for 4.2.5 and 4.2.6, which the wiki never had, from the commit history. - Describe previews and section anchors on GitHub in the contributor guide, and drop the changelog entry about the documentation site. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .readthedocs.yml | 21 --- CHANGELOG.md | 8 +- Docs/Contributing/02-Writing.md | 37 ++--- Docs/Contributing/04-Markdown-Specifics.md | 12 +- Docs/{index.md => README.md} | 33 +++-- Docs/Version-History.md | 152 +++++++++++++++++++++ Docs/requirements.txt | 1 - README.md | 11 +- mkdocs.yml | 57 -------- 9 files changed, 202 insertions(+), 130 deletions(-) delete mode 100644 .readthedocs.yml rename Docs/{index.md => README.md} (86%) create mode 100644 Docs/Version-History.md delete mode 100644 Docs/requirements.txt delete mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index be2da6e..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,21 +0,0 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Required: the build image and the Python version -build: - os: ubuntu-24.04 - tools: - python: "3.12" - -# Build documentation with MkDocs -mkdocs: - configuration: mkdocs.yml - -# Install the MkDocs version that the site is built with -python: - install: - - requirements: Docs/requirements.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index f48741d..22a1a5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,7 @@ All notable changes to this project are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Releases up to -4.2.6 are described in the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki. +4.2.6 are described in the [version history](Docs/Version-History.md). ## [Unreleased] @@ -20,6 +18,8 @@ in the wiki. inputs, outputs, and notes, checked against the source code - Rewrite the home, concepts, examples, and contributor pages to match the current cmdlets, including module settings, privileges, and long paths +- Move the version history and the installation instructions from the wiki + into the documentation, and add the missing notes for 4.2.5 and 4.2.6 ### Fixed @@ -29,7 +29,5 @@ in the wiki. `NTFSSecurity-Help.xml` - Fix documentation examples that did not work, such as restoring permissions from a CSV file and filtering entries by account -- Fix the documentation site navigation, the "Edit on GitHub" links, and the - Read the Docs build configuration [Unreleased]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...HEAD diff --git a/Docs/Contributing/02-Writing.md b/Docs/Contributing/02-Writing.md index be6b2b7..872f263 100644 --- a/Docs/Contributing/02-Writing.md +++ b/Docs/Contributing/02-Writing.md @@ -1,24 +1,25 @@ # Write documentation -The NTFSSecurity documentation is written in Markdown and built into a -website with [MkDocs][mkdocs]. This page explains how the documentation is -organized and how to change it. +The NTFSSecurity documentation is written in Markdown and lives in the +`Docs` folder of the repository, where GitHub renders it. This page explains +how the documentation is organized and how to change it. ## Documentation structure | Path | Content | | --- | --- | -| `Docs/index.md` | Home page with features, requirements, and the cmdlet list | +| `Docs/README.md` | Home page with features, requirements, installation, and the cmdlet list; GitHub shows it when you open the `Docs` folder | | `Docs/Concepts.md` | Background on security descriptors, rights, inheritance, and privileges | | `Docs/Examples.md` | Task-oriented examples | +| `Docs/Version-History.md` | Changes in 4.2.6 and earlier | | `Docs/Cmdlets/*.md` | One reference page per cmdlet, in platyPS format | | `NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml` | Help file that `Get-Help` shows, generated from `Docs/Cmdlets` | | `Docs/Contributing.md`, `Docs/Contributing/*.md` | This contributor guide | -| `mkdocs.yml` | Site settings and navigation | -| `.readthedocs.yml` | Build settings for Read the Docs | | `README.md` | Front page of the GitHub repository | +| `CHANGELOG.md` | Changes since 4.2.6 | -When you add a page, add it to the `nav` section of `mkdocs.yml`. +When you add a page, link to it from `Docs/README.md` or from a related page, +so that readers can find it. ## Markdown editors @@ -59,8 +60,8 @@ Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later, platyPS 0.14.2 adds the `-ProgressAction` common parameter to every page. For a new cmdlet, create the page, replace every placeholder in it, and add -the page to `mkdocs.yml`. Replace `Get-NTFSExample` with the name of the new -cmdlet: +the cmdlet to the cmdlet list in `Docs/README.md`. Replace `Get-NTFSExample` +with the name of the new cmdlet: ```powershell New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets @@ -75,19 +76,12 @@ again and commit it together with the page: New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force ``` -## Preview the website +## Preview your change -MkDocs needs Python. Install the MkDocs version that the site is built with -and start the preview server: - -```powershell -pip install -r Docs/requirements.txt -mkdocs serve -``` - -Open `http://127.0.0.1:8000` in a browser. The preview reloads when you save -a file. Run `mkdocs build --strict` to find broken links and pages that are -missing from the navigation. +GitHub renders the pages with GitHub Flavored Markdown. To preview a page +before you push it, open it in Visual Studio Code and press **Ctrl+Shift+V**. +In a pull request, the **Files changed** tab shows a changed page rendered +when you open its menu (**...**) and select **View file**. ## Check your change @@ -132,7 +126,6 @@ workflow for larger changes in [Get started](01-Getting-Started.md). Read the [Style guide](03-Style-Guide.md). -[mkdocs]: https://www.mkdocs.org/user-guide/writing-your-docs/ [platyps]: https://github.com/PowerShell/platyPS [label-documentation]: https://github.com/raandree/NTFSSecurity/labels/Documentation [label-help-wanted]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted diff --git a/Docs/Contributing/04-Markdown-Specifics.md b/Docs/Contributing/04-Markdown-Specifics.md index d0104cc..e99b2d3 100644 --- a/Docs/Contributing/04-Markdown-Specifics.md +++ b/Docs/Contributing/04-Markdown-Specifics.md @@ -13,7 +13,10 @@ the additional rules for the cmdlet reference pages, which platyPS processes. - Don't use hard tabs or trailing spaces. - Link to other pages with relative links to the `.md` file, for example `[Concepts](Concepts.md)` or `[Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md)`. - MkDocs converts them to links to the generated pages. + GitHub renders them as links to the pages. +- Link to a section with the anchor that GitHub generates from its heading: + lowercase, with spaces replaced by hyphens and punctuation removed, for + example `[Privileges](Concepts.md#privileges)`. - End every file with a single newline. ## Cmdlet reference pages @@ -42,10 +45,3 @@ expects: add a sentence below each one. - In RELATED LINKS, write each link on its own line and separate the links with blank lines. - -## MkDocs - -- The site uses the built-in `readthedocs` theme. -- Every page must be listed in the `nav` section of `mkdocs.yml`. -- Files in `Docs` that aren't Markdown are copied to the website. Exclude - files that don't belong there with `exclude_docs` in `mkdocs.yml`. diff --git a/Docs/index.md b/Docs/README.md similarity index 86% rename from Docs/index.md rename to Docs/README.md index b1f4531..f392f97 100644 --- a/Docs/index.md +++ b/Docs/README.md @@ -38,10 +38,26 @@ Install the module from the Install-Module -Name NTFSSecurity ``` -You can also download a release from the -[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub. -If you have trouble, see -[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). +You can also install a release without the PowerShell Gallery. Download +`NTFSSecurity.zip` from the +[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub +and extract it into a module folder. In an elevated session, these commands +install the module for all users of Windows PowerShell 5.1 and PowerShell 7: + +```powershell +Unblock-File -Path .\NTFSSecurity.zip +Expand-Archive -Path .\NTFSSecurity.zip -DestinationPath "$env:ProgramFiles\WindowsPowerShell\Modules" +``` + +`Unblock-File` removes the mark that Windows adds to downloaded files. If you +extract a marked zip file with File Explorer, the extracted files keep the +mark, and the execution policy `RemoteSigned` stops the module from loading. + +The zip file contains the folder `NTFSSecurity`. Remove an older copy of that +folder first. To install the module only for yourself, extract it into a +folder of `$env:PSModulePath` in your profile instead, for example +`Documents\WindowsPowerShell\Modules` for Windows PowerShell 5.1 or +`Documents\PowerShell\Modules` for PowerShell 7. ## Getting started @@ -138,10 +154,8 @@ them have changed since; use the cmdlet reference for the current names. ## Version history -See the [changelog](https://github.com/raandree/NTFSSecurity/blob/master/CHANGELOG.md) -and the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki. +See the [changelog](../CHANGELOG.md) for the changes since 4.2.6 and the +[version history](Version-History.md) for 4.2.6 and earlier. ## Contributing @@ -149,5 +163,4 @@ Contributions are welcome. See the [contributor guide](Contributing.md). ## License -NTFSSecurity is licensed under the -[MIT license](https://github.com/raandree/NTFSSecurity/blob/master/LICENSE). +NTFSSecurity is licensed under the [MIT license](../LICENSE). diff --git a/Docs/Version-History.md b/Docs/Version-History.md new file mode 100644 index 0000000..ad11586 --- /dev/null +++ b/Docs/Version-History.md @@ -0,0 +1,152 @@ +# Version history + +This page lists the changes in NTFSSecurity 4.2.6 and earlier. It replaces +the version history in the former GitHub wiki. For the changes since 4.2.6, +see the [changelog](../CHANGELOG.md). + +## 4.2.5 and 4.2.6 + +The PowerShell Gallery published 4.2.5 on 2019-07-11 and 4.2.6 on +2019-07-12. The wiki listed no changes for these versions, so this list is +reconstructed from the commit history. + +- Removed `Show-NTFSSimpleAccess`, which used Windows Forms, for + compatibility with PowerShell Core. +- Fixed parameter alias definitions that made importing the module fail, + for example in Service Management Automation + ([#18](https://github.com/raandree/NTFSSecurity/issues/18), + [#36](https://github.com/raandree/NTFSSecurity/issues/36)). +- Fixed the `ToSimpleFileSystemAccessRule2` method of the access entries + that `Get-NTFSAccess` returns + ([#48](https://github.com/raandree/NTFSSecurity/issues/48)). +- Fixed the `ApplyTo` column in the output of `Get-NTFSAccess`. +- Added the MIT license. + +## 4.2.4 + +- Bug fixes. + +## 4.2.3 + +- Added the cmdlet `Get-FileHash2`. +- Bug fixes. + +## 4.2.1 + +- Added the cmdlets `Get-NTFSHardLink`, `New-NTFSHardLink`, and + `New-NTFSSymbolicLink`. + +## 4.2 + +- Added the cmdlets `Move-Item2` and `Copy-Item2`. +- `Remove-Item2`, `Move-Item2`, and `Copy-Item2` now support `-WhatIf` and + `-Confirm`. + +## 4.1 + +- The `-Attributes` parameter of `Get-ChildItem2` works like the one of the + standard cmdlet `Get-ChildItem`, as requested. +- `Remove-NTFSAccess` can now remove access from existing access control + entries. The old behavior is still available with the `-RemoveSpecific` + switch parameter. + +## 4.0 + +- The `*-NTFSAccess` cmdlets can now work on security descriptors to allow + bulk processes. +- Code cleanup for better performance and maintainability. +- Bug fixes. + +## 3.2.3 + +- Fixed a bug in `GetInheritedFrom` that resulted in "Invalid Path" or "Path + not found" errors. + +## 3.2 + +- Bug fixes for managing auditing. +- Fixed various bugs reported on CodePlex. + +## 3.1 + +- All cmdlets have the prefix `NTFS` now. There are aliases for backward + compatibility. +- The new version of `Get-NTFSEffectivePermission` uses `AuthzAccessCheck` + instead of `GetEffectiveRightsFromAcl`. +- The previous `Get-NTFSEffectivePermission` cmdlet has been renamed to + `Get-NTFSEffectivePermissionOld`. +- Added `FileSystemAuditRule2` to the PowerShell formatters. +- Added the `InheritedFrom` information to `FileSystemAuditRule2`. + +## 3.0 + +- This version uses [AlphaFS](https://github.com/alphaleonis/AlphaFS) to + work around the `MAX_PATH` limit of 260 characters. +- New `*-Item2` cmdlets discover items with a long path: + - `Get-ChildItem2` (`dir2`) + - `Get-Item2` (`gi2`) + - `Remove-Item2` (`del2`, `rm2`) +- For inherited access control entries, `InheritedFrom` is displayed. +- Generic access rights are supported. +- Performance improvements. +- Bug fixes. + +## 2.4 + +- `Remove-Access` did not remove deny entries when using the pipeline, for + example `Import-Csv .\access.txt | Remove-Access`. +- `Add-Access` did not remove deny entries when using the pipeline, for + example `Import-Csv .\access.txt | Add-Access`. +- The parameter `-Account` was undiscoverable when using the pipeline. + +## 2.3 + +- The module now makes full use of the Backup, Restore, and Take Ownership + privileges, so as an administrator you can edit permissions on objects + that you don't have explicit access to. Privileges are enabled by default + if the value `EnablePrivileges` is `$true` in `NTFSSecurity.psd1`. The new + cmdlets `Get-Privileges`, `Disable-Privileges`, and `Enable-Privileges` + are for manual control. +- The `-Path` parameter now works consistently. + +## 2.1 + +- Fixed bugs with `Set-Owner`. +- Added support for managing auditing (SACL). + +## 2.0 (beta) + +- New commands: `Get-SimpleAccess`, `Get-SimpleEffectiveAccess`, + `Show-SimpleAccess`, `Show-SimpleEffectiveAccess`, and `Copy-Access`. +- All cmdlets are now written in C#. +- Fixed a number of bugs. + +## 1.3 + +- Fixed an issue with parameter handling. +- Now works with PowerShell 3.0. + +## 1.2 + +- Fixed some issues with path validation. +- Fixed documentation bugs. + +## 1.1 + +- Fixed the issue with square brackets in paths. +- Performance improvements. + +## 1.0 + +- The last tests didn't reveal any issue. PowerShell has a problem handling + files that have square brackets in the file name, and this module inherits + the issue. + +## 0.9 (beta) + +- Fixed some bugs. +- Updated documentation. + +## 0.8 (beta) + +- Initial release. diff --git a/Docs/requirements.txt b/Docs/requirements.txt deleted file mode 100644 index f2caded..0000000 --- a/Docs/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs==1.6.1 diff --git a/README.md b/README.md index b2c0960..42ee37f 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ Install-Module -Name NTFSSecurity ``` You can also download a release from the -[releases page](https://github.com/raandree/NTFSSecurity/releases). If you -have trouble, see -[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install). +[releases page](https://github.com/raandree/NTFSSecurity/releases) and +install it without the PowerShell Gallery; see +[Installation](Docs/README.md#installation). The module runs on Windows in Windows PowerShell 5.1 and PowerShell 7. @@ -43,7 +43,7 @@ Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited ## Documentation -- [Overview](Docs/index.md): features, requirements, and the list of cmdlets +- [Overview](Docs/README.md): features, requirements, and the list of cmdlets - [Concepts](Docs/Concepts.md): security descriptors, access rights, inheritance, privileges, long paths, and module settings - [Examples](Docs/Examples.md): common tasks @@ -59,8 +59,7 @@ although some cmdlet names have changed since: ## Version history See [CHANGELOG.md](CHANGELOG.md) for changes since version 4.2.6 and the -[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History) -in the wiki for earlier releases. +[version history](Docs/Version-History.md) for 4.2.6 and earlier releases. ## License diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index c4f3155..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,57 +0,0 @@ -copyright: "The NTFSSecurity module is licensed under the MIT license." -repo_url: https://github.com/raandree/NTFSSecurity -edit_uri: edit/master/Docs/ -nav: -- Home: ./index.md -- Concepts: ./Concepts.md -- Examples: ./Examples.md -- Cmdlets: - - Add-NTFSAccess: Cmdlets/Add-NTFSAccess.md - - Add-NTFSAudit: Cmdlets/Add-NTFSAudit.md - - Clear-NTFSAccess: Cmdlets/Clear-NTFSAccess.md - - Clear-NTFSAudit: Cmdlets/Clear-NTFSAudit.md - - Copy-Item2: Cmdlets/Copy-Item2.md - - Disable-NTFSAccessInheritance: Cmdlets/Disable-NTFSAccessInheritance.md - - Disable-NTFSAuditInheritance: Cmdlets/Disable-NTFSAuditInheritance.md - - Disable-Privileges: Cmdlets/Disable-Privileges.md - - Enable-NTFSAccessInheritance: Cmdlets/Enable-NTFSAccessInheritance.md - - Enable-NTFSAuditInheritance: Cmdlets/Enable-NTFSAuditInheritance.md - - Enable-Privileges: Cmdlets/Enable-Privileges.md - - Get-ChildItem2: Cmdlets/Get-ChildItem2.md - - Get-DiskSpace: Cmdlets/Get-DiskSpace.md - - Get-FileHash2: Cmdlets/Get-FileHash2.md - - Get-Item2: Cmdlets/Get-Item2.md - - Get-NTFSAccess: Cmdlets/Get-NTFSAccess.md - - Get-NTFSAudit: Cmdlets/Get-NTFSAudit.md - - Get-NTFSEffectiveAccess: Cmdlets/Get-NTFSEffectiveAccess.md - - Get-NTFSHardLink: Cmdlets/Get-NTFSHardLink.md - - Get-NTFSInheritance: Cmdlets/Get-NTFSInheritance.md - - Get-NTFSOrphanedAccess: Cmdlets/Get-NTFSOrphanedAccess.md - - Get-NTFSOrphanedAudit: Cmdlets/Get-NTFSOrphanedAudit.md - - Get-NTFSOwner: Cmdlets/Get-NTFSOwner.md - - Get-NTFSSecurityDescriptor: Cmdlets/Get-NTFSSecurityDescriptor.md - - Get-NTFSSimpleAccess: Cmdlets/Get-NTFSSimpleAccess.md - - Get-Privileges: Cmdlets/Get-Privileges.md - - Move-Item2: Cmdlets/Move-Item2.md - - New-NTFSHardLink: Cmdlets/New-NTFSHardLink.md - - New-NTFSSymbolicLink: Cmdlets/New-NTFSSymbolicLink.md - - Remove-Item2: Cmdlets/Remove-Item2.md - - Remove-NTFSAccess: Cmdlets/Remove-NTFSAccess.md - - Remove-NTFSAudit: Cmdlets/Remove-NTFSAudit.md - - Set-NTFSInheritance: Cmdlets/Set-NTFSInheritance.md - - Set-NTFSOwner: Cmdlets/Set-NTFSOwner.md - - Set-NTFSSecurityDescriptor: Cmdlets/Set-NTFSSecurityDescriptor.md - - Test-Path2: Cmdlets/Test-Path2.md -- Contributing: - - Overview: Contributing.md - - Getting Started: Contributing/01-Getting-Started.md - - Writing: Contributing/02-Writing.md - - Style Guide: Contributing/03-Style-Guide.md - - Markdown Specifics: Contributing/04-Markdown-Specifics.md -site_name: NTFSSecurity -site_description: PowerShell module for managing NTFS permissions, auditing, inheritance, and ownership -theme: readthedocs -site_author: Raimund Andrée, James Smith -docs_dir: ./Docs -exclude_docs: | - /requirements.txt