New-PageHeadingNavigation

Generate navigation specifications for specified headings found in an HTML fragment.

Syntax

 New-PageHeadingNavigation [-HTMLfragment] <Object> [-NavitemSpecs] <Object[]> [-NavTemplate] <Object> [-HeadingLevels] <String>  [<CommonParameters>]

Description

Generates a link specification for each heading in an HTML fragment which

The link specifications have the format required by ConvertTo-NavigationItem to generate navigation bar items.

Parameters

-HTMLfragment <Object>

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 Property Value
Required? true
Position? 1
Default value ``
Accept pipeline input? false
Accept wildcard characters? false

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 Property Value
Required? false
Position? 2
Default value ``
Accept pipeline input? false
Accept wildcard characters? false

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 link template "navheading" 
<span class='navitem{{level}}'>{{navtext}}</span>"

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.

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 Property Value
Required? false
Position? 3
Default value ``
Accept pipeline input? false
Accept wildcard characters? false

-HeadingLevels <String>

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.

Parameter Property Value
Required? false
Position? 4
Default value ``
Accept pipeline input? false
Accept wildcard characters? false

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.

Notes

This function is typically used in the build script Build.ps1 to define the contents of the navigation bar (placeholder {{nav}}).

Examples

EXAMPLE 1

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:

$fragment = '<h2 id="bob">Hello World</h2>'

Output:

<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 2

Hello World</h2>' -NavTemplate $custom

Create an HTML element for navigation to an heading using the custom template $custom.

    $custom = @{ navheading = '<span class="li-item{{level}}">{{navtext}}</span>'}

Output:

<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.

Related Links

Module: MarkDownToHTML; Version: 2.6.1; (c) 2018-2022 WetHat Lab. All rights reserved.