Children

The children shortcode lists child pages in various layouts.

Usage

​
{{% children sort="title" %}}
{{ partial "shortcodes/children.html" (dict
  "page" .
  "sort" "title"
)}}

Parameter

Name Default Notes
type tree The layout used for the listing.

- tree: a nested, unordered list
- list: a non-nested list with titles resembling a heading style depending on the depth
- flat: a non-nested list with titles in standard text style
- card: a card for each top-level children.
    depth will be ignored by the default cardtemplate.
    See below for details
showhidden false When true, child pages hidden from the menu will be displayed as well.
description false When true shows a short text under each page in the list. When no description or summary exists for the page, the first 70 words of the content is taken - read more info about summaries on gohugo.io.
depth 1 The depth of descendants to display. For example, if the value is 2, the shortcode will display two levels of child pages. To get all descendants, set this value to a high number eg. 999.
sort auto The sort criteria of the displayed list.

- auto defaults to ordersectionsby of the page’s Front Matter
    or to ordersectionsby of the configuration Option
    or to default
- weight
- title
- modifieddate
- expirydate
- publishdate
- date
- length
- default adhering to Hugo’s default sort criteria
cardtemplate default If type=card, the template to be used to display a card. See below for details.

Remarks for the Card Type

The card type uses the cards shortcode to display the top-level children of a page. See below for an example.

Each children is displayed in its own card, using the default cardtemplate. With it the card will display

  • a featured image at the start; it is picked automatically checking in the following order and stopping the check once an image was found
    • featured.webp, featured.png, featured.jpg, featured.jpeg
    • cover.webp, cover.png, cover.jpg, cover.jpeg
    • image.webp, image.png, image.jpg, image.jpeg
    • the first image in the bundle
  • the title of the child page as card title
  • if description=true the summary

If you have advanced requirements, you can write your own cardtemplate.

Own Card Templates

The children shortcode displays each children using the card shortcode for display. If you have advanced requirements to display the children, you can place a card layout partial into layouts/partials/card.

For example, if you want to see debug output displaying the parameter the partial receives, you could set cardtemplate=debug which will cause the partial layouts/partials/debug.html to be called. The debug card template is shipped with the theme.

A card template will be called with the following parameter by the children shortcode:

  • page: the page, the children shortcode was contained in
  • content: the summary
  • href: ready to use link to the children page
  • image: ready to use link to the featured image
  • title: title of the children page
  • params.page: the children page
  • params.depth: the shortcodes depth parameter value
  • params.description: the shortcodes description parameter value
  • params.showhidden: the shortcodes showhidden parameter value
  • params.sort: the shortcodes sort parameter value

Examples

All Default

{{% children %}}

With Description

{{% children description="true" %}}
  • page X

    This is a plain page test, and the beginning of a YAML multiline description...

  • page 1

    This is a demo child page

  • page 2

    This is a demo child page with no description. So its content is used as description.

  • page 3

    This is a demo child page

Infinite Depth and Hidden Pages

{{% children depth="999" showhidden="true" %}}

List Type with Depth and Description

{{% children type="list" depth="3" description="true" %}}
page X

This is a plain page test, and the beginning of a YAML multiline description...

page 1

This is a demo child page

page 1-1

This is a demo child page

page 1-1-2 (headless)

This is a demo child page

page 1-1-3

This is a demo child page

page 2

This is a demo child page with no description. So its content is used as description.

page 3

This is a demo child page

page 3-1

This is a plain page test nested in a parent

Flat Type with Depth

{{% children type="flat" depth="3" %}}
page X
page 1
page 1-1
page 1-1-2 (headless)
page 1-1-3
page 2
page 3
page 3-1

Card Type with Description

{{% children type="card" description="true" %}}

  • This is a plain page test, and the beginning of a YAML multiline description...

  • This is a demo child page with no description. So its content is used as description.

Subsections of Children

page X

This is a plain demo child page X.

Subsections of page 1

Subsections of page 1-1

page 1-1-2 (headless)

Subsections of page 1-1-2 (headless)

page 2

This is a demo child page with no description.

So its content is used as description.

Subsections of page 3