Get-DocumentLink

  8 minute read  

Get-DocumentLink

SYNOPSIS

Retrieves links from a Markdown document with their metadata.

SYNTAX

FilterByKind (Default)

Get-DocumentLink
 [-Path <String[]>]
 [-Document <ParsedDocument[]>]
 [-IncludeKind <LinkKind[]>]
 [-ExcludeKind <LinkKind[]>]
 [-MatchMarkdown <Regex>]
 [-MatchText <Regex>]
 [-MatchDestination <Regex>]
 [-MatchReferenceID <Regex>]
 [-NotMatchMarkdown <Regex>]
 [-NotMatchText <Regex>]
 [-NotMatchDestination <Regex>]
 [-NotMatchReferenceID <Regex>]
 [<CommonParameters>]

FilterByOnly

Get-DocumentLink
 [-Path <String[]>]
 [-Document <ParsedDocument[]>]
 [-Only <String>]
 [-MatchMarkdown <Regex>]
 [-MatchText <Regex>]
 [-MatchDestination <Regex>]
 [-MatchReferenceID <Regex>]
 [-NotMatchMarkdown <Regex>]
 [-NotMatchText <Regex>]
 [-NotMatchDestination <Regex>]
 [-NotMatchReferenceID <Regex>]
 [<CommonParameters>]

DESCRIPTION

The Get-DocumentLink cmdlet gets the links in a Markdown document with their metadata, including the Kind of each link and its Position. You can use it to get the links directly from one or more files with the Path parameter or pass it a set of parsed documents (as returned by the Get-Document cmdlet) with the Document parameter.

You can use the remaining parameters to filter the list of links for the one’s you’re looking for, such as inline links or links with undefined references.

EXAMPLES

This example retrieves the list of links from the project changelog. The results show the Kind, Position, and actual Markdown for every link. They also show the relevant metadata for the link as defined in the document.

Get-DocumentLink -Path ./CHANGELOG.md

Kind        : TextUsingReference
Text        : Keep a Changelog
Destination :
Title       :
ReferenceID : 01
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:5:24
Markdown    : [Keep a Changelog][01]

Kind        : TextUsingReference
Text        : Semantic Versioning
Destination :
Title       :
ReferenceID : 02
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:6:1
Markdown    : [Semantic Versioning][02]

Kind        : TextUsingReference
Text        : Documentarian
Destination :
Title       :
ReferenceID : 03
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:16:3
Markdown    : [Documentarian][03]

Kind        : TextUsingReference
Text        : Documentarian.DevX
Destination :
Title       :
ReferenceID : 04
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:17:3
Markdown    : [Documentarian.DevX][04]

Kind        : ReferenceDefinition
Text        :
Destination : https://keepachangelog.com/en/1.0.0/
Title       :
ReferenceID : 01
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:19:0
Markdown    : [01]: https://keepachangelog.com/en/1.0.0/

Kind        : ReferenceDefinition
Text        :
Destination : https://semver.org/spec/v2.0.0.html
Title       :
ReferenceID : 02
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:20:0
Markdown    : [02]: https://semver.org/spec/v2.0.0.html

Kind        : ReferenceDefinition
Text        :
Destination : Source/Modules/Documentarian/CHANGELOG.md
Title       :
ReferenceID : 03
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:21:0
Markdown    : [03]: Source/Modules/Documentarian/CHANGELOG.md

Kind        : ReferenceDefinition
Text        :
Destination : Source/Modules/Documentarian.DevX/CHANGELOG.md
Title       :
ReferenceID : 04
Position    : C:\code\pwsh\Documentarian\CHANGELOG.md:22:0
Markdown    : [04]: Source/Modules/Documentarian.DevX/CHANGELOG.md

In this example, Get-DocumentLink lists the inline links from documents in a folder, then groups them by filename and lists their count.

Get-DocumentLink -Path .\reference\ -Only Inline |
    Group-Object -Property { $_.Position.FileInfo.FullName } |
    Select-Object -Property Count, Name

Count  Name
-----  ----
    3  C:\docs\reference\classes\DocumentLink\constructors.md
    1  C:\docs\reference\classes\DocumentLink\methods\HasReference.md
    1  C:\docs\reference\classes\DocumentLink\methods\IsImage.md
    1  C:\docs\reference\classes\DocumentLink\methods\IsReference.md
    1  C:\docs\reference\classes\DocumentLink\methods\IsSelfReferential.md
    1  C:\docs\reference\classes\DocumentLink\methods\IsText.md
    2  C:\docs\reference\classes\DocumentLink\methods\Parse.md
    1  C:\docs\reference\classes\LinkKindTransformAttribute\constructors.md
    1  C:\docs\reference\classes\LinkKindTransformAttribute\methods\Transform.md
    1  C:\docs\reference\classes\ParsedDocument\constructors.md
    1  C:\docs\reference\classes\ParsedDocument\methods\InlineLinks.md
    2  C:\docs\reference\classes\ParsedDocument\methods\ParsedLinks.md
    1  C:\docs\reference\classes\ParsedDocument\methods\ToDecoratedString.md
    1  C:\docs\reference\classes\ParsedDocument\methods\UndefinedReferenceLinks.md
    1  C:\docs\reference\classes\ParsedDocument\methods\UnusedReferenceLinkDefinitions.md
    1  C:\docs\reference\classes\ParsedDocument\methods\ValidReferenceLinksAndDefinitions.md
    1  C:\docs\reference\classes\ParsingPatterns\methods\InsideSingleBacktick.md
    2  C:\docs\reference\classes\ParsingPatterns\methods\InSquareBrackets.md
    1  C:\docs\reference\classes\ParsingPatterns\methods\NotInsideInlineCode.md
    1  C:\docs\reference\classes\Position\constructors.md
    1  C:\docs\reference\classes\Position\methods\ToString.md
    1  C:\docs\reference\cmdlets\_index.md
    1  C:\docs\reference\cmdlets\Get-Document.md
    1  C:\docs\reference\cmdlets\Get-DocumentLink.md

In this example, Get-Document is used to parse every Markdown document in the reference folder and save it to the $docs variable. Then, Get-DocumentLink gets every reference link and definition from those parsed documents, grouping the results by Kind.

$docs = Get-Document -Path .\reference
Get-DocumentLink -Document $docs -Only References |
    Group-Object -Property Kind |
    Select-Object -Property Name, Count

Name                Count
----                -----
TextSelfReference       8
TextUsingReference    132
ReferenceDefinition   121

In this example, Get-Document is used to parse every Markdown document in the reference folder and save it to the $docs variable. Then, Get-DocumentLink uses the MatchDestination parameter to filter for only those links and reference link definition whose Destination starts with http: or https:.

$docs = Get-Document -Path .\reference
Get-DocumentLink -Document $docs -MatchDestination '^https?:'

Kind        : ReferenceDefinition
Text        :
Destination : https://learn.microsoft.com/powershell/module/microsoft.powershell
              .core/about/about_comparison_operators#-like-and--notlike
Title       :
ReferenceID : 02
Position    : C:\docs\reference\classes\LinkKindTransformAttribute\methods\
              Transform.md:49:0
Markdown    : [02]: https://learn.microsoft.com/powershell/module/microsoft
              .powershell.core/about/about_comparison_operators#-like-and--notlike

Kind        : ReferenceDefinition
Text        :
Destination : https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-VT100-Mode
Title       :
ReferenceID : 01
Position    : C:\docs\reference\classes\ParsedDocument\methods\ToDecoratedString.md:41:0
Markdown    : [01]: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-VT100-Mode

Kind        : ReferenceDefinition
Text        :
Destination : https://learn.microsoft.com/dotnet/api/system.text.regularexpressions
              .regex.escape
Title       :
ReferenceID : 01
Position    : C:\docs\reference\classes\ParsingPatterns\methods\InsideSingleBacktick
              .md:67:0
Markdown    : [01]: https://learn.microsoft.com/dotnet/api/system.text
              .regularexpressions.regex.escape

Kind        : TextInline
Text        : about_CommonParameters
Destination : http://go.microsoft.com/fwlink/?LinkID=113216
Title       :
ReferenceID :
Position    : C:\docs\reference\cmdlets\Get-Document.md:41:244
Markdown    : [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216)

Kind        : TextInline
Text        : about_CommonParameters
Destination : http://go.microsoft.com/fwlink/?LinkID=113216
Title       :
ReferenceID :
Position    : C:\docs\reference\cmdlets\Get-DocumentLink.md:408:1
Markdown    : [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216)

PARAMETERS

-Document

Specify one or more ParsedDocument object, as output by the Get-Document cmdlet, to return get links from.

Type: ParsedDocument[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-ExcludeKind

Specify one or more LinkKind enums to exclude from the list of returned links. If you specify a wildcard character, such as *, the cmdlet filters all matching LinkKind enums.

Only links whose Kind property isn’t in the list of enums specified by this parameter are returned.

Type: LinkKind[]
Parameter Sets: FilterByKind
Aliases:
Accepted values: TextInline, TextSelfReference, TextUsingReference, ImageInline, ImageSelfReference, ImageUsingReference, ReferenceDefinition

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludeKind

Specify one or more LinkKind enums to include for the list of returned links. If you specify a wildcard character, such as *, the cmdlet filters all matching LinkKind enums.

Only links whose Kind property is in the list of enums specified by this parameter are returned.

Type: LinkKind[]
Parameter Sets: FilterByKind
Aliases:
Accepted values: TextInline, TextSelfReference, TextUsingReference, ImageInline, ImageSelfReference, ImageUsingReference, ReferenceDefinition

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-MatchDestination

Specify a regular expression to check against the value of the Destination property for the links. Only links with a Destination property whose value matches the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-MatchMarkdown

Specify a regular expression to check against the value of the Markdown property for the links. Only links with a Markdown property whose value matches the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-MatchReferenceID

Specify a regular expression to check against the value of the ReferenceID property for the links. Only links with a ReferenceID property whose value matches the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-MatchText

Specify a regular expression to check against the value of the Text property for the links. Only links with a Text property whose value matches the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-NotMatchDestination

Specify a regular expression to check against the value of the Destination property for the links. Only links with a Destination property whose value doesn’t match the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-NotMatchMarkdown

Specify a regular expression to check against the value of the Markdown property for the links. Only links with a Markdown property whose value doesn’t match the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-NotMatchReferenceID

Specify a regular expression to check against the value of the ReferenceID property for the links. Only links with a ReferenceID property whose value doesn’t match the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-NotMatchText

Specify a regular expression to check against the value of the Text property for the links. Only links with a Text property whose value doesn’t match the regular expression are returned.

Type: Regex
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Only

Specify a preset filter for the links to return. Valid options include:

  • Inline - return only the links that are defined inline
  • References - return only reference links and definitions
  • UndefinedReferences - return only reference links that don’t have a matching definition
  • UnusedReferences - return only reference link definitions that don’t have a matching link
  • ValidReferences - return only reference links that have definitions and reference link definitions that are used.
Type: String
Parameter Sets: FilterByOnly
Aliases:
Accepted values: Inline, References, UndefinedReferences, UnusedReferences, ValidReferences

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Path

Specify the path to one or more files or folders. The cmdlet parses the specified values for Markdown documents and returns the links defined in them.

Type: String[]
Parameter Sets: (All)
Aliases: FullName

Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: True

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String[]

You can pass a list of file and folder paths to this cmdlet to parse for Markdown links.

ParsedDocument[]

You can pass a list of ParsedDocument objects to this cmdlet to return links from.

OUTPUTS

This cmdlet returns DocumentLink objects.

NOTES

Get-Document

Last modified March 17, 2023: (MAINT) Conform Documentarian to PlayPS (ed19a5d)