Update-ReadmeIndex.ps1

<#PSScriptInfo
.VERSION 1.0.1
.AUTHOR Roman Kuzmin
.COPYRIGHT (c) Roman Kuzmin
.TAGS Markdown README Index TOC
.GUID 0ab2bbcb-6552-415f-a102-7799e8a051b8
.LICENSEURI http://www.apache.org/licenses/LICENSE-2.0
.PROJECTURI https://github.com/nightroman/PowerShelf
#>

<#
.Synopsis
	Updates README index from content directories.
	Author: Roman Kuzmin

.Description
	The command scans the contents recursively, finds README.md files and
	builds the index from their first line headings in the root README.md.

	The generated list with links is inserted into the root README.md.
	The index start/end marks are defined by the HTML comments like:
	given $Content='docs', marks are '<!--docs-->'.

.Parameter Content
		Specifies the directory to scan with the path relative to root.
		Use '/' as directory separators if it is not the top directory.

.Parameter Root
		Specifies the root directory with README.md to be updated.
		The typical use case is a git repository root.
		Default: the current location

.Parameter Depth
		Specifies the recursive scan depth.
		Default: 0, just top directories.

.Parameter Descending
		Tells to sort top directories descending.

.Parameter NoWarning
		Tells not to write warnings about no README.

.Parameter Skip
		The script returning true for the directories to skip.
		Argument 1: directory path like $Content[/dir1[/...]]

.Link
	Example: https://github.com/nightroman/PowerShellTraps

.Link
	https://github.com/nightroman/PowerShelf
#>

[CmdletBinding()]
param(
	[Parameter(Position=0, Mandatory=1)]
	[string]$Content
	,
	[string]$Root = '.'
	,
	[int]$Depth
	,
	[switch]$Descending
	,
	[switch]$NoWarning
	,
	[scriptblock]$Skip
)

$ErrorActionPreference = 1
trap { Write-Error $_ }

# Gets markdown list lines with links to folders recursively.
function Get-List($Path, $Level) {
	$indent = '    ' * $Level

	# get and sort (top) directory names
	$dirNames = Get-ChildItem -LiteralPath $Path -Name -Directory
	if ($Level -eq 0) {
		$dirNames = $dirNames | Sort-Object -Descending:$Descending
	}

	foreach($dirName in $dirNames) {
		$dirPath = "$Path/$dirName"
		if ($Skip -and (& $Skip $dirPath)) {
			continue
		}

		$README = "$dirPath/README.md"

		# case: no README
		if (!(Test-Path -LiteralPath $README)) {
			if ($Level -lt $Depth -and (Get-ChildItem -LiteralPath $dirPath -Recurse -Filter README.md)) {
				# output the list line with the folder name
				'{0}- {1}' -f $indent, $dirName

				# process sub-folders
				Get-List $dirPath ($Level + 1)
			}
			elseif (!$NoWarning) {
				Write-Warning "Found no README in '$dirPath'."
			}
			continue
		}

		# the first README line is heading, get the topic text
		switch -File $README -Regex {
			'^#{1,6}(.*)' {
				$topic = $matches[1].Trim()
				break
			}
			default {
				throw "Expected first line heading in '$README'."
			}
		}

		# output the list line with the topic link
		'{0}- [{1}]({2})' -f $indent, $topic, $dirPath

		# process sub-folders
		if ($Level -lt $Depth) {
			Get-List $dirPath ($Level + 1)
		}
	}
}

### main

$Root = $PSCmdlet.GetUnresolvedProviderPathFromPSPath($Root)
if (!(Test-Path -LiteralPath $Root)) {
	throw "Cannot find '$Root'."
}

$README = "$Root/README.md"
if (!(Test-Path -LiteralPath $README)) {
	throw "Cannot find '$README'."
}

$Mark = "<!--$Content-->"

### collect lines before and after marks
$lines1 = [System.Collections.Generic.List[string]]@()
$lines2 = [System.Collections.Generic.List[string]]@()
$step = 1
foreach($_ in Get-Content -LiteralPath $README) {
	if ($step -eq 1) {
		$lines1.Add($_)
		if ($_ -eq $Mark) {
			++$step
		}
		continue
	}

	if ($step -eq 2) {
		if ($_ -eq $Mark) {
			$lines2.Add($_)
			++$step
		}
		continue
	}

	$lines2.Add($_)
}

if ($step -ne 3) {
	throw "Cannot find two marks '$Mark' in '$README'."
}

### update README
$(
	Push-Location -LiteralPath $Root
	try {
		$lines1
		Get-List $Content 0
		$lines2
	}
	finally {
		Pop-Location
	}
) | Set-Content -LiteralPath $README -Encoding UTF8