Docs

List

Use the list content block to show a list of articles.
Overview Default List Filtered List Category Filter Responsive Tables Custom List Arguments Background Type Heading Type Input Type

Overview  

The list block renders a list of articles.

Default List  

Recent Articles
Title Description
Fourth Post This is the fourth blog post. It is excluded from the search index.
Third Post This is the third blog post. It uses exact case for the title.
Second Post This is the second blog post.
First Post This is the first blog post.
yml 
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: blog
    reverse: true
    sort: date
  hide_empty: false
  background:
    color: body-tertiary
    subtle: false
  justify: start

Filtered List  

Add the following configuration to your page’s frontmatter to enable data table features:

---
modules: ["simple-datatables"]
---

You can then use sortable, paginate, and searchable to enable inline sorting and filtering.

Recent Articles
Title Description
First Post This is the first blog post.
Second Post This is the second blog post.
Third Post This is the third blog post. It uses exact case for the title.
Fourth Post This is the fourth blog post. It is excluded from the search index.
yml 
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: blog
    reverse: false
    sort: date
  pagination: 5
  hide_empty: false
  background:
    color: body-tertiary
    subtle: false
  justify: start
  sortable: true
  paginate: true
  searchable: true

Category Filter  

Use filter to add a button group above the table that shows only rows matching a specific category. Set filter_col to the zero-indexed column in your hook’s table that contains the category value. An All button is always prepended and selected by default.

The filter works alongside sortable, paginate, and searchable — sorting and pagination continue to operate on the filtered result set.

Recent Articles
Article Category Published
First Post featured 2022-10-01
Second Post featured 2022-11-01
Third Post tutorial 2022-12-01
Fourth Post tutorial 2023-01-01
yml 
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: blog
    reverse: false
    sort: date
  hide_empty: false
  hook: assets/table-filter-hook
  filter:
    - featured
    - tutorial
  filter_col: 1
  sortable: true
  background:
    color: body-tertiary
    subtle: false
  justify: start

Define the hook partial in your site’s layouts/_partials folder. The following example renders a custom Markdown table that includes a category column sourced from each page’s front matter.

{{ $pages := .pages | default dict }}

{{ $content := printf "| %s | %s | %s |\n|-|-|-|\n" (T "article") (T "category") (T "published") }}
{{ range $pages }}
    {{ $cat := .Params.category | default "general" }}
    {{ if site.Params.env_bookshop_live }}
        {{ $content = printf "%s[%s](#!) | %s | %s |\n" $content .title $cat (now | time.Format "2006-01-02") }}
    {{ else }}
        {{ $content = printf "%s[%s](%s) | %s | %s |\n" $content .LinkTitle .RelPermalink $cat
            (.PublishDate | time.Format "2006-01-02")
        }}
    {{ end }}
{{ end }}

{{ return $content }}

Set filter_responsive to replace the button group with a dropdown below the site’s main breakpoint. A group of more than a few categories is wider than a phone, and the button group does not wrap. The dropdown and the button group stay in step, so moving across the breakpoint never changes which category is selected. It defaults to false, so a list keeps its button group at every width unless you ask otherwise.

Responsive Tables  

A table with several columns runs off the side of a small screen. Set wrap to move a record’s last column onto a row of its own below the site’s main breakpoint, which is usually enough when one column holds most of the width — a description, say.

Set wrap_cols when it is not. It takes a column count per rendered row, so a record folds into groups and stacks as a card. "1,2" across the three-column hook below keeps the article on the lead row and folds the category and published date onto a row beneath it.

Only the first group keeps one cell per column, so it alone stays aligned down the table; every later group lays its values out in equal columns that reduce in number to fit the viewport. The counts must be positive and add up to the number of columns your hook renders — a list that does not, such as one left behind when a column was added, is refused and the table falls back to wrapping the last column only.

Folded columns hide their headings, so their values appear without labels. That suits self-describing content such as badges, which is why the grouping is yours to choose rather than derived.

Recent Articles
Article Category Published
First Post featured 2022-10-01
Second Post featured 2022-11-01
Third Post tutorial 2022-12-01
Fourth Post tutorial 2023-01-01
yml 
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: blog
    reverse: false
    sort: date
  hide_empty: false
  hook: assets/table-filter-hook
  wrap: true
  wrap_cols: "1,2"
  sortable: true
  background:
    color: body-tertiary
    subtle: false
  justify: start

Custom List  

Customize the list by providing a hook partial.

Recent Articles
Article Published
First Post 2022-10-01
Second Post 2022-11-01
Third Post 2022-12-01
Fourth Post 2023-01-01
yml 
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: blog
    reverse: false
    sort: date
  hide_empty: false
  hook: assets/table-hook
  background:
    color: body-tertiary
    subtle: false
  justify: start
  sortable: true

Define the hook partial in your site’s layouts/_partials folder. The following example renders a custom Markdown table consisting of the article’s title and publication date.

{{ $pages := .pages | default dict }}

{{ $content := printf "| %s | %s |\n|-|-|\n" (T "article") (T "published") }}
{{ range $pages }}
    {{ if site.Params.env_bookshop_live }}
        {{ $content = printf "%s[%s](#!) | %s |\n" $content .title  (now | time.Format "2006-01-02") }}
    {{ else }}
        {{ $content = printf "%s[%s](%s) | %s |\n" $content .LinkTitle .RelPermalink 
            (.PublishDate | time.Format "2006-01-02") 
        }}
    {{ end }}
{{ end }}

{{ return $content }}

Arguments  

The content block supports the following arguments:

Name Type Required Default Comment
_bookshop_name string Alias for _bookshop_name.
Alias for _bookshop_name.
_ordinal int Zero-based position of the bookshop component within the page’s component hierarchy.
Zero-based position of the bookshop component within the page’s component hierarchy.
background background, string Background style of the section.
Background style of the section.
bg_class string Background class attributes of the element. It supports Bootstrap attributes to modify the background styling of the element.
Background class attributes of the element. It supports Bootstrap attributes to modify the background styling of the element.
class string Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
cover bool Flag indicating if the element should be rendered as a cover section, filling most of the viewport height. Defaults to 88vh rather than the full 100vh, so the next section peeks above the fold; see the site settings main.sectionHeight and main.maxSectionHeight.
Flag indicating if the element should be rendered as a cover section, filling most of the viewport height. Defaults to 88vh rather than the full 100vh, so the next section peeks above the fold; see the site settings main.sectionHeight and main.maxSectionHeight.
filter string, slice Slice of category values used to render a filter button group above the element. Each value becomes a button label. An “All” button is always prepended. Uses the text content of the column at filter-col to match rows.
Slice of category values used to render a filter button group above the element. Each value becomes a button label. An “All” button is always prepended. Uses the text content of the column at filter-col to match rows.
filter_col int 1 Zero-indexed column number whose text content is matched against the active filter value. Defaults to 1. Only used when filter is set.
Zero-indexed column number whose text content is matched against the active filter value. Defaults to 1. Only used when filter is set.
filter_responsive bool Whether the filter button group collapses into a dropdown below the site’s main breakpoint, for groups too wide to fit a narrow viewport. Defaults to false, so the button group renders at every width. Only used when filter is set, and has no effect when the main breakpoint is xs.
Whether the filter button group collapses into a dropdown below the site’s main breakpoint, for groups too wide to fit a narrow viewport. Defaults to false, so the button group renders at every width. Only used when filter is set, and has no effect when the main breakpoint is xs.
fluid bool true Flag to set the section container to fluid design, else the section is limited to xxl.
Flag to set the section container to fluid design, else the section is limited to xxl.
heading Heading Heading of the content block, including a preheading and content element.
Heading of the content block, including a preheading and content element.
heading_level int Heading level of the title, from 1 (h1) to 6 (h6). Set 0 to render a div instead of a heading. Content blocks receive a level from the page that renders them, so the first titled block of a page without a page header becomes its h1.
Heading level of the title, from 1 (h1) to 6 (h6). Set 0 to render a div instead of a heading. Content blocks receive a level from the page that renders them, so the first titled block of a page without a page header becomes its h1.
hide_empty bool Hides the entire section when no pages are available.
Hides the entire section when no pages are available.
hook string Render hook for the element’s partial.
Render hook for the element’s partial.
id string Unique identifier of the current element.
Unique identifier of the current element.
input Input yes List input of the element. Uses the name of the section to retrieve known pages.
List input of the element. Uses the name of the section to retrieve known pages.
justify select start Justification of the child elements. Supported values: [start, end, center, between, around, evenly].
Justification of the child elements. Supported values: [start, end, center, between, around, evenly].
limit int Maximum number of elements to display.
Maximum number of elements to display.
overlay_mode select Overlay mode of the element, overrides the site’s general configuration. Supported values: [light, dark, none].
Overlay mode of the element, overrides the site’s general configuration. Supported values: [light, dark, none].
paginate bool Flag indicating if pagination should be added to the element, if the list exceeds the maximum number of containing elements to display.
Flag indicating if pagination should be added to the element, if the list exceeds the maximum number of containing elements to display.
pagination int Number of elements per page in pagination, overrides site settings.
Number of elements per page in pagination, overrides site settings.
pagination_select string Sets the per page options in the dropdown. Must be an array of integers or arrays in the format [label (string), value (int)]. Requires paginate = true. It is recommended to configure values that are a multitude of the pagination value.
Sets the per page options in the dropdown. Must be an array of integers or arrays in the format [label (string), value (int)]. Requires paginate = true. It is recommended to configure values that are a multitude of the pagination value.
searchable bool Toggle the ability to search the dataset.
Toggle the ability to search the dataset.
section_class string Section class attributes of the element. It supports Bootstrap attributes to modify the section styling of the element.
Section class attributes of the element. It supports Bootstrap attributes to modify the section styling of the element.
sortable bool Toggle the ability to sort the columns.
Toggle the ability to sort the columns.
theme select Color theme to apply to the element. Supported values: [light, dark].
Color theme to apply to the element. Supported values: [light, dark].
width int 8 Column width of the element. For embedded elements, the width is relative to the parent’s container.
Column width of the element. For embedded elements, the width is relative to the parent’s container.
wrap bool Toggle the last column to wrap to a new row on smaller devices.
Toggle the last column to wrap to a new row on smaller devices.
wrap_cols string Comma-separated column count per rendered row when wrapping, summing to the table’s column count. Folds a record across more than two rows on small devices, for example “2,4,1”. Only the first group keeps one cell per column; later groups collapse into a single spanning cell. Requires wrap; a list that does not sum to the column count falls back to wrapping the last column only.
Comma-separated column count per rendered row when wrapping, summing to the table’s column count. Folds a record across more than two rows on small devices, for example “2,4,1”. Only the first group keeps one cell per column; later groups collapse into a single spanning cell. Requires wrap; a list that does not sum to the column count falls back to wrapping the last column only.
wrapper string Class attribute of the element’s wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the fa-wrapper and fa-fluid attributes by default.
Class attribute of the element’s wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the fa-wrapper and fa-fluid attributes by default.

Background Type  

Name Type Required Default Comment
backdrop string Background image with a mask to improve contrast.
Background image with a mask to improve contrast.
class string Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element.
color select Theme color of the element. Supported values: [primary, secondary, success, danger, warning, info, light, dark, white, black, body, body-tertiary].
Theme color of the element. Supported values: [primary, secondary, success, danger, warning, info, light, dark, white, black, body, body-tertiary].
subtle bool Apply subtle theme colors.
Apply subtle theme colors.

Heading Type  

Name Type Required Default Comment
align select start Alignment of the headline, content, or icon. Supported values: [start, center, end].
Alignment of the headline, content, or icon. Supported values: [start, center, end].
arrangement select above Arrangement of the preheading, either left or above the header. On smaller screens, the preheading is always placed on top. Supported values: [above, first].
Arrangement of the preheading, either left or above the header. On smaller screens, the preheading is always placed on top. Supported values: [above, first].
content string, template.HTML Section content displayed below the title.
Section content displayed below the title.
preheading string Preheading of the section heading.
Preheading of the section heading.
size int 4 Display size of the headline.
Display size of the headline.
title string, hstring.RenderedString, hstring.HTML, template.HTML Title of the element. If the element references a (local) page, the title overrides the referenced page’s title.
Title of the element. If the element references a (local) page, the title overrides the referenced page’s title.
width int Column width of the element. For embedded elements, the width is relative to the parent’s container.
Column width of the element. For embedded elements, the width is relative to the parent’s container.

Input Type  

Name Type Required Default Comment
categories string, slice Categories to be used as filter. When set, only pages that belong to at least one of the provided categories are retrieved.
Categories to be used as filter. When set, only pages that belong to at least one of the provided categories are retrieved.
keywords string, slice Keywords to be used as filter. When set, only pages that match at least one of the provided keywords are retrieved.
Keywords to be used as filter. When set, only pages that match at least one of the provided keywords are retrieved.
nested bool If set, retrieves all pages below the section or current page recursively. By default, only first-order children are retrieved.
If set, retrieves all pages below the section or current page recursively. By default, only first-order children are retrieved.
reverse bool true Sets the sort order to descending.
Sets the sort order to descending.
section string Name of the content section.
Name of the content section.
sort select yes Key to sort by. Supported values: [date, title, weight].
Key to sort by. Supported values: [date, title, weight].
tags string, slice Tags to be used as filter. When set, only pages that match at least one of the provided tags are retrieved.
Tags to be used as filter. When set, only pages that match at least one of the provided tags are retrieved.
• docs(list): document responsive filter controls and column groups (3c9809c)

On this page

Follow Me

I work on everything coding and tweet developer memes