Skip to content

ConvertTo-NavigationItem

SYNOPSIS

Convert a navigation specification to a single item in a navigation bar of a static HTML site projects created by `New-StaticHTMLSiteProject`.

SYNTAX

ConvertTo-NavigationItem [[-NavSpec] <Object>] [[-RelativePath] <String>] [[-NavTemplate] <Object>]
 [<CommonParameters>]

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.

EXAMPLES

EXAMPLE 1

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:

\<button class='navitem'\>
    \<a href="https://github.com/WetHat/MarkdownToHtml"\>Project HOME\</a\>
\</button\>\<br/\>

EXAMPLE 2

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:

\<button class="navitem"\>
    \<a href="../index.html"\>Index\</a\>
\</button\>

EXAMPLE 3

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:

    $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:

\<li class="li-item"\>
    \<a href="../index.html"\>Index\</a\>
\</li\>

EXAMPLE 4

ConvertTo-NavigationItem @{'---'=''} -RelativePath 'intro/about.md'

Generates a separator line in the navigation bar.

Output:

\<hr class="navitem" /\>

EXAMPLE 5

ConvertTo-NavigationItem @{'---'=''} -NavTemplate $custom

Generates a separator line in the navigation bar using a custom template `$custom`:

    $custom = @{ navseparator = '\<hr class="li-item" /\>'}

Output:

\<hr class="li-item" /\>

EXAMPLE 6

ConvertTo-NavigationItem @{'Introduction'=''}

Generates a label in the navigation bar.

Output:

\<div class='navitem'\>Introduction\</div\>

EXAMPLE 7

ConvertTo-NavigationItem @{'Introduction'=''} -NavTemplate $custom

Generates a label in the navigation bar using the custom template `$custom`:

    $custom = @{ navlabel = '\<div class='li-item'\>Introduction\</div\>'}

Output:

\<div class='li-item'\>Introduction\</div\>

PARAMETERS

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

Type: System.Object
Parameter Sets: (All)
Aliases:

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

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

Type: System.String
Parameter Sets: (All)
Aliases:

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

-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 
Type: System.Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: $defaultNavTemplate
Accept pipeline input: False
Accept wildcard characters: False

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

Objects or hashtables with one NoteProperty or key.

OUTPUTS

HTML element representing one navigation item for use in a vertical navigation

bar.

NOTES

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

https://wethat.github.io/MarkdownToHtml/2.5.0/ConvertTo-NavigationItem.html

New-StaticHTMLSiteProject

New-PageHeadingNavigation

Back to top