DevXToolkit

1.6.0

Public/Invoke-MkDocs.ps1

function Invoke-MkDocs {
    <#
    .SYNOPSIS
    Creates a docs folder with starter markdown files.

    .DESCRIPTION
    Scaffolds docs/index.md, docs/architecture.md, and docs/usage.md with simple stubs.
    Existing files are not overwritten unless -Force is used.

    .PARAMETER Force
    Overwrites existing docs files when present.

    .EXAMPLE
    mkdocs
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
        'PSUseSingularNouns',
        '',
        Justification = 'Retained for backward compatibility with the published command name.'
    )]
    [CmdletBinding(SupportsShouldProcess = $true)]
    [OutputType([System.IO.FileInfo])]
    [Alias('mkdocs')]
    param(
        [switch]$Force
    )

    $docsDir = Join-Path -Path (Get-Location) -ChildPath 'docs'
    if (-not $PSCmdlet.ShouldProcess($docsDir, 'Write documentation scaffold')) {
        return
    }

    if (-not (Test-Path -LiteralPath $docsDir)) {
        New-DtDirectory -Path $docsDir -Force:$Force -Confirm:$false | Out-Null
    }

    $files = @(
        @{ Name = 'index.md'; Content = "# Documentation`n`nTODO: Add documentation overview." },
        @{ Name = 'architecture.md'; Content = "# Architecture`n`nTODO: Describe system architecture." },
        @{ Name = 'usage.md'; Content = "# Usage`n`nTODO: Add usage examples and workflows." }
    )

    foreach ($file in $files) {
        $path = Join-Path -Path $docsDir -ChildPath $file.Name
        Set-DtFileContent -Path $path -Content $file.Content -Force:$Force -Confirm:$false | Out-Null
    }

    foreach ($file in $files) {
        $path = Join-Path -Path $docsDir -ChildPath $file.Name
        if (Test-Path -LiteralPath $path) {
            [System.IO.FileInfo]::new($path)
        }
    }
}