MarkdownToHtml

2.7.0

SiteNavigation.psm1

# Default template specifications for page navigation
$SCRIPT:defaultNavTemplate = @{
     navitem      = '<button class="navitem"><a href="{{navurl}}">{{navtext}}</a></button>';
     navlabel     = '<div class="navlabel">{{navtext}}</div>';
     navseparator = '<hr/>';
     navheading   = '<span class="navitem{{level}}">{{navtext}}</span>'
}

# find headings h1 .. h6 in an HTML fragment.
$SCRIPT:hRE   = New-Object regex '<h(\d)[^<>]* id="([^"])+"[^<]*>(.+?)\s*(?=<\/h\d.*|$)'

# Match an hyperlink
$SCRIPT:aRE = New-Object regex '</{0,1} *a[^>]*>'

Set-Alias -Name 'ConvertTo-PageHeadingNavigation' -Value 'New-PageHeadingNavigation'

<#
.SYNOPSIS
Generate navigation specifications for specified headings found in an HTML
fragment.
 
.DESCRIPTION
Generates a link specification for each heading in an HTML fragment which
* has an `id` attribute
* matches heading level constraint
 
The link specifications have the format required by `ConvertTo-NavigationItem`
to generate navigation bar items.
 
.PARAMETER HTMLfragment
HTML fragment object whose HTMLfragment property contains a HTMLfragment string.
Such objects are generated by `Convert-MarkdownToHTMLFragment`.
 
For backward compatibility this parameter can also be a plain string representing
the HTML fragment. This is deprecated.
 
.PARAMETER NavitemSpecs
 
Navigation specification for links which are to appear on every page right
before the page heading navigation links.
 
Usually this specification is something like:
 
`@{ '---' = ''}`
: to add a separator line between the site navigation links from the
    page heading navigation links.
 
`@{ 'Page Contents' = ''}`
: to add the label _Page Contents_ separating the site navigation links from
    the page heading navigation links.
 
However, all link specifications supported by the `NavitemSpecs`
of the function `New-SiteNavigation` are supported for this parameter too.
 
**Note!** If this parameter is specified, the HTMLfragment parameter must be
a HTML fragment object (such as the one returned by
`Convert-MarkdownToHTMLFragment`).
 
.PARAMETER NavTemplate
An optional dictionary of the named HTML template needed to add a heading
link to the navigation bar. The dictionary should at least contain a
`navheading` specification:
 
+ :--------: + :----------: + ----------------------------------------
| Type | Key | HTML Template
+ ========== + ============ + ========================================
| Heading | "navheading" | ~~~ html
| link | |<span class='navitem{{level}}'>{{navtext}}</span>"
| template | | ~~~
+ ---------- + ------------ + ----------------------------------------
 
The HTML template above is the value defined in
`Build.json`. That value is used if the given dictionary does not define the
"navheading" mapping or if no dictionary is given at all. Additional mappings
contained in the dictionary not used by this function.
 
For more customization options see
[Static Site Project Customization](about_MarkdownToHTML.md#static-site-project-customization).
 
The css styles used in the template is defined in `md-styles.css`.
 
Following placeholders in the HTML template are recognized.
 
| Placeholder | Description
| :-----------: | -----------
| `{{level}}` | heading level.
| `{{navtext}}` | heading text
 
During the build process the placeholders are replaced with content taken from
the `NavSpec` parameter.
 
.PARAMETER HeadingLevels
A string of numbers denoting the levels of the headings to add to the navigation
bar. By default the headings at level 1,2 and 3 are added to the Navigation bar.
If headings should not be automatically added to the navigation bar, use the
empty string `''` for this parameter. If omitted, the default configuration
defined by option "capture_page_headings" in `Build.json` is used.
 
.INPUTS
None. This function does not read from a pipe.
 
.OUTPUTS
HTML elements representing navigation links to headings on the input HTML
fragment for use in the navigation bar of sites created by
`New-StaticHTMLSiteProject`.
 
.EXAMPLE
New-PageHeadingNavigation $fragment -HeadingLevels '234'
 
Create an HTML element for navigation to page headings `<h2>`, `<h3>`, `<h4>`.
All other headings are ignored. `$fragment` is a HTML framgment defined as:
 
~~~ PowerShell
$fragment = '<h2 id="bob">Hello World</h2>'
~~~
 
Output:
 
~~~ HTML
<button class="navitem">
   <a href="#bob"><span class="navitem2">Hello World</span></a>
</button>
~~~
 
Note that the heading level has been added to the css class.
 
.EXAMPLE
New-PageHeadingNavigation '<h2 id="bob">Hello World</h2>' -NavTemplate $custom
 
Create an HTML element for navigation to an heading using the custom template `$custom`.
 
~~~ PowerShell
    $custom = @{ navheading = '<span class="li-item{{level}}">{{navtext}}</span>'}
~~~
 
Output:
 
~~~ HTML
<button class="navitem">
    <a href="#bob"><span class="li-item2">Hello World</span></a>
</button>
~~~
 
Note that the heading level is used as a postfix for the css class.
 
.NOTES
This function is typically used in the build script `Build.ps1` to define
the contents of the navigation bar (placeholder `{{nav}}`).
 
.LINK
https://wethat.github.io/MarkdownToHtml/2.7/New-PageHeadingNavigation.html
.LINK
`Convert-MarkdownToHTMLFragment`
.LINK
`ConvertTo-NavigationItem`
.LINK
`New-SiteNavigation`
.LINK
`New-StaticHTMLSiteProject`
#>
function New-PageHeadingNavigation {
    [OutputType([string])]
    [CmdletBinding()]
    param(
        [parameter(Mandatory=$true,ValueFromPipeline=$false)]
        [ValidateNotNull()]
        [object]$HTMLfragment,

        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [object[]]$NavitemSpecs,

        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [object]$NavTemplate,

        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [string]$HeadingLevels
    )
    # determine the values of missing parameters
    if ($cfg = $HTMLFragment.EffectiveConfiguration) {
        if (!$NavTemplate -and ($navbar = $cfg.navigation_bar )) {
            $NavTemplate = $navbar.templates
        }
        if (!$HeadingLevels -and $navbar -and $navbar.capture_page_headings) {
            $HeadingLevels = $navbar.capture_page_headings
        }
    }
    # provide defaults if needed
    if (!$NavTemplate) {
            $NavTemplate = $SCRIPT:defaultNavTemplate
    }
    if (!$HeadingLevels) {
            $HeadingLevels = "123" # capture levels 1 .. 3 by default
    }

    # Emit the page header navbar items

    if ($NavitemSpecs -and $HTMLfragment.RelativePath) {
        New-SiteNavigation -NavitemSpecs $NavitemSpecs `
                    -RelativePath $HTMLfragment.RelativePath `
                    -NavTemplate  $NavTemplate
    }
    if ($HTMLfragment -isnot [string]) {
        # fall back to string for backwards compatibility
        $HTMLfragment = $HTMLfragment.HTMLfragment
    }

    $HTMLfragment -split "`n" | ForEach-Object {
        $m = $hRE.Match($_)
        if ($m.Success -and $m.Groups.Count -eq 4) {
            # found an heading with an id attribute
            $level = $m.Groups[1].Captures.Value
            if ($headingLevels.Contains($level)) {
                # this level is enabled
                $id = $m.Groups[2].Captures -join ''
                $txt = $m.Groups[3].Captures -join ''
                # strip hyperlinks in heading text
                $txt = $aRE.Replace($txt,'')
                [string]$navheading = $NavTemplate.navheading
                if (!$navheading) {
                    $navheading = $SCRIPT:defaultNavTemplate.navheading
                }
                @{ $navheading.Replace('{{level}}',$level).Replace('{{navtext}}',$txt) = "#$($id)"}
            }
        }
    } | ConvertTo-NavigationItem -NavTemplate $NavTemplate
}

function Get-NavSpecKey {
    param(
        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [ValidateNotNull()]
        [object]$NavSpec
    )
    if ($NavSpec -is [hashtable]) {
        $NavSpec.Keys | Where-Object {!$_.Equals('NavRoot')}
    } else { # json object
        (Get-Member -InputObject $NavSpec -MemberType NoteProperty | Where-Object {!$_.Name.Equals('NavRoot')}).Name
    }
}

<#
.SYNOPSIS
Convert a navigation specification to a single item in a navigation bar of pages
in a static HTML site project created by `New-StaticHTMLSiteProject`.
 
.DESCRIPTION
Converts the specification for a single item in the navigation bar by
* finding an HTML template to represent the item in the navigation bar.
* replacing placeholders in the template by data taken from the
  specification.
* adjusting the navigation link based on the location in the directory tree.
 
.PARAMETER RelativePath
The path to a Markdown (`*.md`) or HTML (`*.html`) file relative to its
corresponding root configured in `Build.json`. For Markdown files the
root is configured by parameter `"markdown_dir"` for html files it is
`"site_dir"`. This parameter will be used to compute relative resource
and navigation bar links for the HTML page currently
being assembled.
 
The given path should use forward slash '/' path separators.
 
.PARAMETER NavSpec
An object or dictionary with exactly one `NoteProperty` or key representing
a single key-value pair. This parameter provides the data for one item in
the navigation bar.
 
Following key-value pairs are recognized:
 
+ :----: + :---: + :--------: + ---------------------------------------------- +
| Key | Value | Template | Description
| | | Name |
+ ====== + ===== + ========== + ============================================== +
|"_text_"|"_url_"| navitem | A clickable hyperlink where _text_ is the link
| | | | text and _url_ a link to a web page, a relative
| | | | path to a local Markdown file, or a local
| | | | directory containing Markdown files. Links
| | | | must be relative to the project root, unless
| | | | the navigation specification is defined
| | | | in a `Build.json` which is **not** at the
| | | | project root, but somewhere below `markdown_dir`.
| | | | In that case the link must be relative to that
| | | | `Build.json` file.
+ ------ + ----- + ---------- + ---------------------------------------------- +
|"_text_"| "" | navlabel | A label without hyperlink.
+ ------ + ----- + ---------- + ---------------------------------------------- +
| "---" | "" |navseparator| A speparator line.
+ ------ + ----- + ---------- + ---------------------------------------------- +
 
The structure of the data determines the type of navigation bar item to build.
The table above maps supported key-value combinations to the associated named
HTML templates.
 
.PARAMETER NavTemplate
An optional dictionary of named HTML templates.
 
+ :--------: + :----------: + ----------------------------------------
| Type | Key | HTML Template
+ ========== + ============ + ========================================
| clickable | "navitem" | ~~~ html
| link | | <button class='navitem'>
| | | <a href='{{navurl}}'>{{navtext}}</a>
| | | </button>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
| label (no | "navlabel" | ~~~ html
| link) | | <div class='navlabel'>{{navtext}}</div>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
| separator |"navseparator"| ~~~ html
| | | <hr/>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
 
The HTML templates listed represent are the values configured in `Build.json`.
These values are used for keys not provided in the given dictionary or if no
dictionary is given at all. Additional mappings contained in dictionary are
ignored.
 
For more customization options see
[Static Site Project Customization](about_MarkdownToHTML.md#static-site-project-customization).
 
The css styles used in the templates are defined in `md-styles.css`.
 
During the build process the placeholders contained in the HTML template
are replaced with content extracted from the `NavSpec` parameter .
 
| Placeholder | Description
| :-----------: | -----------
| `{{navurl}}` | hyperlink to web-page or local file.
| `{{navtext}}` | link or label text
 
.INPUTS
Objects or hashtables with one NoteProperty or key.
 
.OUTPUTS
HTML element representing one navigation item for use in a vertical navigation
bar.
 
.EXAMPLE
ConvertTo-NavigationItem @{'Project HOME'='https://github.com/WetHat/MarkdownToHtml'} -RelativePath 'intro/about.md'
 
Generates a web navigation link to be put on the page `intro/about.md`.
Note:
the parameter `RelativePath` is specified but not used because the link is
non-local.
 
Output:
 
~~~ html
<button class='navitem'>
    <a href="https://github.com/WetHat/MarkdownToHtml">Project HOME</a>
</button><br/>
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'Index'='index.md'} -RelativePath 'intro/about.md'
 
Generates a navigation link relative to `intro/about.md`. The
link target `index.md` is a page at the root of the same site, hence the link is
adjusted accordingly.
 
Output:
 
~~~ html
<button class="navitem">
    <a href="../index.html">Index</a>
</button>
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'Index'='index.md'} -RelativePath 'intro/about.md' -NavTemplate $custom
 
Generates a navigation link relative to `intro/about.md`.
A custom template definition `$custom` is used:
 
~~~ PowerShell
    $custom = @{ navitem = '<li class="li-item"><a href="{{navurl}}">{{navtext}}</a></li>'}
~~~
 
The link target `index.md` is a page at the root of the same site, hence the link is
adjusted accordingly.
 
Output:
 
~~~ html
<li class="li-item">
    <a href="../index.html">Index</a>
</li>
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'---'=''} -RelativePath 'intro/about.md'
 
Generates a separator line in the navigation bar. The _RelativePath_ parameter
is not used (the specification does not contain a link).
 
Output:
 
~~~ html
<hr class="navitem" />
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'---'=''} -NavTemplate $custom
 
Generates a separator line in the navigation bar using a custom template `$custom`:
 
~~~ PowerShell
    $custom = @{ navseparator = '<hr class="li-item" />'}
~~~
 
Output:
 
~~~ html
<hr class="li-item" />
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'Introduction'=''}
 
Generates a label in the navigation bar.
 
Output:
 
~~~ html
<div class='navitem'>Introduction</div>
~~~
 
.EXAMPLE
ConvertTo-NavigationItem @{'Introduction'=''} -NavTemplate $custom
 
Generates a label in the navigation bar using the custom template `$custom`:
 
~~~ PowerShell
    $custom = @{ navlabel = '<div class='li-item'>Introduction</div>'}
~~~
 
Output:
 
~~~ html
<div class='li-item'>Introduction</div>
~~~
 
.NOTES
This function is typically used in the build script `Build.ps1` to define
the contents of the navigation bar (placeholder `{{nav}}`).
 
.LINK
https://wethat.github.io/MarkdownToHtml/2.7/ConvertTo-NavigationItem.html
.LINK
`New-StaticHTMLSiteProject`
.LINK
`New-PageHeadingNavigation`
#>
function ConvertTo-NavigationItem {
    [OutputType([string])]
    [CmdletBinding()]
    param(
        [parameter(Mandatory=$false,ValueFromPipeline=$true)]
        [ValidateNotNull()]
        [object]$NavSpec,
        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [string]$RelativePath = '',
        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [object]$NavTemplate = $defaultNavTemplate
    )
    PROCESS {
        # create page specific navigation links by making the path relative to
        # the current location specified by `RelativePath`
        $name = Get-NavSpecKey -NavSpec $NavSpec
        $link = $NavSpec.$name

        if ([string]::IsNullOrWhiteSpace($link)) {
            if ($name.StartsWith('---')) { # separator line
                [string]$navseparator = $NavTemplate.navseparator
                if (!$navseparator) {
                    $navseparator = $SCRIPT:defaultNavTemplate.navseparator
                }
                Write-Output $navseparator # separator
            } else { # label
                [string]$navlabel = $NavTemplate.navlabel
                if (!$navlabel) {
                    $navlabel = $SCRIPT:defaultNavTemplate.navlabel
                }
                Expand-HtmlTemplate -InputObject $navlabel -ContentMap @{'{{navtext}}' = $name}
            }
        } else {
            # we have an actual link
            if (!$link.StartsWith('http')) {
                # handle fragment on page

                $hash = $link.IndexOf('#')

                switch ($hash) {
                    {$_ -eq 0 } { # '#target'
                        $file = ''
                        $fragment = $link
                        Break
                    }
                    {$_ -ge 0} {
                        $file = $link.Substring(0,$hash)
                        $fragment = $link.Substring($hash)
                        Break
                    }
                    default {
                        $file = $link
                        $fragment = ''
                    }
                }

                # fix file type
                if ($file.EndsWith('.md') -or $file.EndsWith('.markdown')) {
                    $file = [System.IO.Path]::ChangeExtension($file,'html')
                 }

                # Re-assemble the link
                $link = $file + $fragment
            }

            [string]$navitem = $NavTemplate.navitem
            if (!$navitem) {
                $navitem = $SCRIPT:defaultNavTemplate.navitem
            }

            # optimize the path if the nav spec has a NavRoot property
            if ($NavSpec.NavRoot) {
                $fromPathSegments = $RelativePath.Split("\")
                $toPathSegments = $NavSpec.NavRoot.Split("\")
                [int]$n = [Math]::min($fromPathSegments.Length, $toPathSegments.Length)
                [int]$unique=0
                while ($fromPathSegments[$unique] -eq $toPathSegments[$unique] -and $unique -lt $n) {
                    $unique++
                }
                $relpath = $fromPathSegments[$unique..$($fromPathSegments.Count-1)] -join '/'
            } else {
                $relpath = $RelativePath.Replace('\','/')
            }

            Expand-HtmlTemplate -InputObject $navitem -ContentMap @{
                '{{navurl}}'  = $link
                '{{navtext}}' = $name
            } |  Update-ResourceLinks -RelativePath $relpath
        }
    }
}

<#
.SYNOPSIS
Expand directory link targets one level to links to contained markdown files.
 
.DESCRIPTION
Scans a collection of navigation links for link targets pointing to directories
and inserts links to all directly contained markdown files.
 
.PARAMETER LiteralPath
Absolute path to the directory the navigation itens are relative to. Usually
this is the path to the directory containing the `Build.json` file the navigation
items are from or the directory configured by `markdown_dir` if the navigation
items are from the top-level `Build.json` file.
 
.PARAMETER NavSpec
The specification of a single navigation item as specified in
`ConvertTo-NavigationItem`.
 
.INPUTS
Specifications of navigation items as specified in
`ConvertTo-NavigationItem`.
 
.OUTPUTS
Specification of navigation items as specified in
`ConvertTo-NavigationItem` where all links to directories
are replaced by links to the directory contents (one level).
 
.EXAMPLE
@{'My Directory' = 'foo'} | Expand-DirectoryNavigation -LiteralPath e:\stuff
 
Expands the directory `foo` which is a subdirectory of `e:\stuff`.
Assuming the following directory structure and content:
 
~~~bob
e:\stuff
    |
    '- foo
        |
        +- bar.md
        |
        '- baz.md
~~~
 
where `bar.md` and `baz.md` are two markdown files.
 
This expands to:
 
~~~PowerShell
@{'My Directory' = ""} # <- label
@{'bar' = "foo/bar.md"} # <- link
@{'baz' = "foo/baz.md"} # <- link
~~~
 
.LINK
https://wethat.github.io/MarkdownToHtml/2.7/Expand-DirectoryNavigation.html
.LINK
`ConvertTo-NavigationItem`
#>
function Expand-DirectoryNavigation {
    [OutputType([System.IO.FileInfo])]
    [CmdletBinding()]
    param (
        [parameter(Mandatory=$true,ValueFromPipeline=$false)]
        [ValidateNotNullorEmpty()]
        [string]$LiteralPath,
        [parameter(Mandatory=$true,ValueFromPipeline=$true)]
        [ValidateNotNullorEmpty()]
        [object]$NavSpec
    )

    PROCESS {
        # get the name of the navigation link
        $name = Get-NavSpecKey -NavSpec $NavSpec
        $link = $NavSpec.$name
        if ($link) {
            $target = Join-Path $LiteralPath $link
            if ([System.IO.Directory]::Exists($target)) {
                # target is indeed a director - expand
                # first emit a label
                @{ $name = ''}
                # followed by the file contents
                Get-ChildItem $target -File -Filter '*.m*' `
                | Where-Object { $_.Extension -in '.md','.markdown'} `
                | ForEach-Object {
                    $relpath = Join-Path $link $_.Name
                    @{ $_.BaseName = $relpath}
                }
            } else {
                # Pass through
                $NavSpec
            }
        } else {
            # Pass through
            $NavSpec
        }
    }
}


<#
.SYNOPSIS
Build navigation bar content for a HTML page from a specification and
redering templates
 
.DESCRIPTION
A navigation bar section for a HTML page is built by:
* processing a list of item specification which define the navigation bar
  content
* picking the appropriate HTML template for each navigation bar item
  and expanding the template using data from the item specification
 
.PARAMETER NavitemSpecs
An array where each item is an object or dictionary with exactly one NoteProperty`
or key representing a single key-value pair. This parameter provides the data
for **one** item in the navigation bar.
 
Following key-value pairs are recognized:
 
+ :----: + :---: + :--------: + ---------------------------------------------- +
| Key | Value | Template | Description
| | | Name |
+ ====== + ===== + ========== + ============================================== +
|"_text_"|"_url_"| navitem | A clickable hyperlink where _text_ is the link
| | | | text and _url_ a link to a web page or a local
| | | | Markdown file. Local file links must be
| | | | relative to the project root.
+ ------ + ----- + ---------- + ---------------------------------------------- +
|"_text_"| "" | navlabel | A label without hyperlink.
+ ------ + ----- + ---------- + ---------------------------------------------- +
| "---" | "" |navseparator| A speparator line.
+ ------ + ----- + ---------- + ---------------------------------------------- +
 
The structure of the data determines the type of navigation bar item to build.
The table above maps supported key-value combinations to the associated named
HTML templates.
 
.PARAMETER RelativePath
The path to a Markdown (`*.md`) or HTML (`*.html`) file relative to its
corresponding root configured in `Build.json`. For Markdown files the
root is configured by parameter `"markdown_dir"` for HTML files it is
`"site_dir"`. This parameter will be used to compute relative resource
and navigation bar links for the HTML page currently
being assembled.
 
The given path should use forward slash '/' path separators.
 
.PARAMETER NavTemplate
An optional dictionary of named HTML templates.
 
+ :--------: + :----------: + ----------------------------------------
| Type | Key | HTML Template
+ ========== + ============ + ========================================
| clickable | "navitem" | ~~~ html
| link | | <button class='navitem'>
| | | <a href='{{navurl}}'>{{navtext}}</a>
| | | </button>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
| label (no | "navlabel" | ~~~ html
| link) | | <div class='navlabel'>{{navtext}}</div>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
| separator |"navseparator"| ~~~ html
| | | <hr/>
| | | ~~~
+ ---------- + ------------ + ----------------------------------------
 
The HTML templates listed represent are the values configured in `Build.json`.
These values are used for keys not provided in the given dictionary or if no
dictionary is given at all. Additional mappings contained in dictionary are
ignored.
 
For more customization options see
[Static Site Project Customization](about_MarkdownToHTML.md#static-site-project-customization).
 
The css styles used in the templates are defined in `md-styles.css`.
 
During the build process the placeholders contained in the HTML template
are replaced with content extracted from the `NavSpec` parameter .
 
| Placeholder | Description
| :-----------: | -----------
| `{{navurl}}` | hyperlink to web-page or local file.
| `{{navtext}}` | link or label text
 
.INPUTS
None
 
.OUTPUTS
HTML fragment for a navigation bar.
 
.EXAMPLE
New-SiteNavigation -NavitemSpecs $specs -RelativePath 'a/b/c/bob.md'
 
Create navigation content for a file with relative path `a/b/c/bob.md` and
the specification `$specs` and default templates:
 
`$specs` is defined like so:
 
~~~PowerShell
$specs = @(
    @{ "<img width='90%' src='logo.png' />" = "README.md" },
    @{ "README" = "" },
    @{ "Home" = "README.md" },
    @{ "---" = "" }
)
~~~
 
Output:
 
~~~ html
<button class="navitem">
   <a href="../../../README.html">
      <img width='90%' src='../../../logo.png' />
   </a>
</button>
<div class="navlabel">README</div>
<button class="navitem">
   <a href="../../../README.html">Home</a>
</button>
<hr/>
~~~
 
Note how the relative path parameter was used to update the links.
 
.LINK
https://wethat.github.io/MarkdownToHtml/2.7/New-SiteNavigation.html
#>
function New-SiteNavigation {
    [OutputType([string])]
    [CmdletBinding()]

    param(
        [parameter(Mandatory=$true,ValueFromPipeline=$false)]
        [ValidateNotNull()]
        [object[]]$NavitemSpecs,

        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [string]$RelativePath = '',

        [parameter(Mandatory=$false,ValueFromPipeline=$false)]
        [object]$NavTemplate = $defaultNavTemplate
    )

    $NavitemSpecs | ConvertTo-NavigationItem -RelativePath $RelativePath `
                                             -NavTemplate $NavTemplate
}

# SIG # Begin signature block
# MIIFYAYJKoZIhvcNAQcCoIIFUTCCBU0CAQExCzAJBgUrDgMCGgUAMGkGCisGAQQB
# gjcCAQSgWzBZMDQGCisGAQQBgjcCAR4wJgIDAQAABBAfzDtgWUsITrck0sYpfvNR
# AgEAAgEAAgEAAgEAAgEAMCEwCQYFKw4DAhoFAAQUGlreekMxk0yCl5ArRGpt/27Q
# BoqgggMAMIIC/DCCAeSgAwIBAgIQaejvMGXYIKhALoN4OCBcKjANBgkqhkiG9w0B
# AQUFADAVMRMwEQYDVQQDDApXZXRIYXQgTGFiMCAXDTIwMDUwMzA4MTMwNFoYDzIw
# NTAwNTAzMDgyMzA0WjAVMRMwEQYDVQQDDApXZXRIYXQgTGFiMIIBIjANBgkqhkiG
# 9w0BAQEFAAOCAQ8AMIIBCgKCAQEArNo5GzE4BkP8HagZLFT7h189+EPxP0pmiSC5
# yi34ZctnpyFUz+Cv547+MvzAr0uRuLkxn6ArBkVLeHVAB58jenSeLwDFls5gS0I+
# pRJWO9eyyT64EcUSCMlfMLW2q1hzjfFckFR6iFnGp3TkE0s1kQANUNjAR9axC6ju
# 4dpilIupCHW+/0s9aGz7LYuRQGcy3uIL9TURKdBtOsMOBeclUsEoFSEp/0D30E8r
# PNk/VLu57G5H9n3HuX/DSBR2CL8LzOOv981hiS+SCds/pHqjCX9Qj+j47Kv7xZ1i
# ha2fg4AEHDGbL/WJGnTpUKath+EmgmFRlsP7PgnZr4anvGdcdQIDAQABo0YwRDAO
# BgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwMwHQYDVR0OBBYEFKtE
# 8xMwn4kGbe8AzXY0ineK5ToHMA0GCSqGSIb3DQEBBQUAA4IBAQAgaUJkHD9192H7
# OUhf9W3gR0ZkApD5fnPqsIgS91JFQ2fCnonudJinwbODs01yA55uUw4GJUnAKQOx
# 6auVAC5KVzE2dMDbOrBOseoKj12EbzbF509FkVoT5O77NDpFrGErR1zmQ8fd1DXw
# FAFC1x1vpxW7/F6g+xewpqlFKzjkPeEvLgyoUmKMCOnT0JdXS0BfyAyyIfHwvILo
# 2eJWVG2UMioKOJ6vsttTu8mQgVZlfcoF6r81ee3hTEK24aHNR+frHmyrL9UplZxD
# AuoUGVzYdDyOejlLPm+d+ew1d6dTf9QfurRxoKgI6OMOVI3iIIXd6HTiIW4ACwI9
# iUjry3dVMYIByjCCAcYCAQEwKTAVMRMwEQYDVQQDDApXZXRIYXQgTGFiAhBp6O8w
# ZdggqEAug3g4IFwqMAkGBSsOAwIaBQCgeDAYBgorBgEEAYI3AgEMMQowCKACgACh
# AoAAMBkGCSqGSIb3DQEJAzEMBgorBgEEAYI3AgEEMBwGCisGAQQBgjcCAQsxDjAM
# BgorBgEEAYI3AgEVMCMGCSqGSIb3DQEJBDEWBBTRJ8ceivmxd7Vlt6sZNLohRn7k
# 7DANBgkqhkiG9w0BAQEFAASCAQBLSFYKLKqx8bYgvnC23E2I46osZIO6V+tyEmkt
# KOUMXqL/6rxYB6ZPfGvVPLgX8ZZEK/SxDzmZzYneu20p84Ef+QKdolTabWq5ntqc
# 3W/7Y+W8dwwKrXaad7wACRV9KtBRKeiSlJnz6PRckKhDjCpCMu1v1u51wHYItPRW
# qcLpeY/nQsJHd092YpiQMK7o8ITO06V9dEIc1tjlVMHY0j2b2zZdAgCETrrck7pR
# kaehLk22ytoxfgdcvQwi3wFHt4EfaQu1Lx1ENl8O3BwqRDJp//G6djRKyDjbiqP7
# gV3IDoy7TL3Yr/lO/810fqX31EfEmG/0DyjyqCkO+RG59Z2f
# SIG # End signature block