Silk

0.2.0

Functions/Split-MarkdownTopic.ps1


function Split-MarkdownTopic
{
    <#
    .SYNOPSIS
    Parses a Markdown-formatted module help topic, e.g. about_Module.
 
    .DESCRIPTION
    A Markdown-formatted help topic should contain four sections, `Topic`, `Short Description`, `Long Description`, and `See Also`. These should all be formatted as level-1 headings. For example:
 
        # Topic
 
        about_Silk
 
        # Short Description
 
        Silk is a PowerShell module used to convert another module's help system into an HTML website.
 
        # Long Description
 
        MOre details here. Yadda, yadda, yadda.
 
        # See Also
 
        about_Silk_AdditionalTopic
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        # The root where the config file was found.
        $ConfigFileRoot,

        [Parameter(Mandatory=$true,ValueFromPipeline=$true)]
        # An object containing information about the topic to parse.
        $TopicInfo
    )
    process
    {
        Set-StrictMode -Version Latest

        $path = $TopicInfo.Path
        if( -not (Test-Path -Path $path -PathType Leaf) )
        {
            Write-Error ('Markdown help topic <{0}> not found.' -f $path)
            return
        }

        $content = New-Object Collections.ArrayList
        $sectionName = $null
        $eof = [Guid]::NewGuid().ToString()
        $topic = New-Object PsObject -Property @{ Name = ''; Synopsis = ''; Description = ''; RelatedLinks = ''; FileName = $TopicInfo.FileName }
        $lineNum = 0
        Invoke-Command { Get-Content -Path $path ; $eof } | ForEach-Object {
            if( $_ -match '^# (.*)$' -or $_ -eq $eof )
            {
                if( $sectionName -or $_ -eq $eof )
                {
                    $topic.$sectionName = $content -join "`n"
                    $topic.$sectionName = $topic.$sectionName.Trim()
                    if( $_ -eq $eof )
                    {
                        return
                    }
                    $content.Clear()
                }


                $sectionName = $matches[1]
                switch -Regex ($sectionName)
                {
                    'Topic|Name' 
                    {
                        $sectionName = 'Name'
                    }
                    'Short Description|Synopsis'
                    {
                        $sectionName = 'Synopsis'
                    }
                    'Long Description|Description'
                    {
                        $sectionName = 'Description'
                    }
                    'See Also|(Related )?Links?'
                    {
                        $sectionName = 'RelatedLinks'
                    }
                    default
                    {
                        Write-Error ('{0}: line {1}: Unknown top-level heading <{2}>. Expected <Name>, <Synopsis>, <Description>, or <Link>. <Link> may be used multiple times.' -f $path,$lineNum,$_)
                    }
                }
            }
            else
            {
                if( -not $sectionName )
                {
                    Write-Error ('{0}: line {1}: Invalid Markdown help topic: the first line must be `# Name`.' -f $path,$lineNum)
                    return
                }
                [void] $content.Add( $_ )
            }
            ++$lineNum
        }

        if( $TopicInfo | Get-Member Title )
        {
            $topic.Name = $TopicInfo.Title
        }
        return $topic
    }
}