The [sitetree] Shortcode

With the [sitetree] shortcode you can insert in any Post, Page or Custom Post any sort of hyper-list that SiteTree is able to generate. The [sitetree] shortcode, however, doesn't allow you to add to your website a large, paginated Site Tree, for this reason the shortcode functionality is more of a complement than an alternative to the Site Tree feature.

One Shortcode, Many Hyper-lists

Where is the magic? The magic is in the type attribute, the only attribute to be required. In fact, if you try to insert the shortcode bare-bones, not a single hyper-list will take its place.

The following is the most concise example of shortcode-call:

[sitetree type="page"]

The type attribute identifies the kind of the hyper-list, and it is always a singular word. Valid values are post, page, {custom_post_type_key}, post_tag, category, {custom_taxonomy_key} and author. According to the value of the type attribute, a whole set of other attributes become available. These, detailed in the next sections, are your means to customise the hyper-list you want to create.

Attributes Common to All Types of Hyper-list

title

Description: the title of the hyper-list. The title is tagged with an <h3> heading tag, and included in the <div> container wrapping the hyper-list.

Default value: the name of the content type, generally in the plural.

show_title

(true/false) Whether or not to show the title of the hyper-list.

Default value: true

limit

Description: the maximum number of items to show in the hyper-list.

Valid values: a positive integer up to 1000.

Default value: 100

Attributes Common to Hyper-lists of Type 'post', 'page' and {custom_post_type_key}

exclude

Description: comma-separated record of Posts, Pages or Custom Posts IDs to exclude from the hyper-list. The content excluded with this attribute sum to the Posts, Pages or Custom Posts excluded via the SiteTree meta-box.

Valid values: comma-separated list of positive integers.

include_only

Description: whitelist of IDs. Every Post, Page or Custom Post out of this record doesn't show up in the hyper-list.

Valid values: comma-separated list of positive integers.

include_globally_excluded

Description: a boolean (true/false) telling SiteTree whether or not to show the Posts, Pages or Custom Posts excluded from all the shortcode-generated hyper-lists, or a whitelist of IDs that have been globally excluded. For information on how to exclude Posts, Pages and Custom Posts from all the shortcode-generated hyper-lists, have a look at "Excluding Web Pages".

Valid values: true/false or a comma-separated list of positive integers.

Default value: false

When type is 'post'

group_by

Description: tells SiteTree whether and how to group Posts.

Valid values: none, date, category, author

Default value: none

hyperlink_group_title

(true/false) Whether or not to hyperlink the title of each group. Posts have to be grouped via the group_by attribute in order for SiteTree to take this attribute into account.

Default value: true

order_by

Description: tells SiteTree how to order the hyper-list of Posts.

Valid values: post_date, post_date_asc, comment_count, post_title

Default value: post_date

pop_stickies

(true/false) Whether or not to stick featured Posts to the top of the hyper-list.

Default value: false

show_excerpt

(true/false) Whether or not to show for each Post a short excerpt.

Default value: false

excerpt_length

Description: sets the maximum number of characters (whitespaces included) making the excerpt shown for each Post. The show_excerpt attribute has to be set to true in order for SiteTree to take this attribute into account.

Valid values: a positive integer between 50 and 300.

Default value: 100

show_comments_count

(true/false) Whether or not to show for each Post the date of publication.

Default value: false

When type is 'page'

show_home

(true/false) Whether or not to show a "Home" link on top of the hyper-list.

Default value: false

hierarchical

(true/false) Whether to show a hierarchical or flat hyper-list of Pages.

Default value: true

order_by

Description: tells SiteTree how to order the hyper-list of Pages.

Valid values: menu_order, title

Default value: menu_order

group_by_topic

(true/false) Tells SiteTree whether or not to group Pages by Topic.

Default value: false

show_topicless

(true/false) Tells SiteTree whether or not to show Pages without a Topic.

Default value: false

exclude_children

(true/false) Whether or not to exclude all the child Pages from the hyper-list.

Default value: false

only_children_of

Description: setting it to a Page ID, SiteTree will show a hyper-list of Pages children of the chosen page. When equal to the string this, instead, a hyper-list of Pages children of the Page containing the shortcode will be shown.

Valid values: this, or a positive integer.

dehyperlink_parents

(true/false) Whether or not to disable the hyperlinking of parent Pages.

Default value: false

dehyperlinking_level

Description: tells SiteTree up to which level of nesting a hierarchical hyper-list of Pages has to have its parent items de-hyperlinked. The dehyperlink_parents attribute has to be set to true in order for SiteTree to take this attribute into account.

Valid values: 0, 1, 2

Default value: 0

When type is {custom_post_type_key}

order_by

Description: tells SiteTree how to order the hyper-list of Custom Posts.

Valid values: post_title, post_date, post_date_asc

Default value: post_title

hierarchical

(true/false) Whether to show a hierarchical or flat hyper-list of Custom Posts. This attribute is available only for hierarchical Custom Post Types.

Default value: true

When type is 'post_tag'

show_count

(true/false) Whether or not to show the number of Posts published under each Post Tag.

Default value: false

order_by

Description: tells SiteTree how to order the hyper-list of Post Tags.

Valid values: name, count

Default value: name

When type is 'category'

show_count

(true/false) Whether or not to show for each Category the number of published Posts.

Default value: true

feed_text

Description: text of the link to each Category's RSS feed. When no text is specified, the link is hidden.

Default value: empty string.

hierarchical

(true/false) Whether to show a hierarchical or flat hyper-list of Categories.

Default value: true

order_by

Description: tells SiteTree how to order the hyper-list of Categories.

Valid values: name, count

Default value: name

When type is {custom_taxonomy_key}

order_by

Description: tells SiteTree how to order the hyper-list of Terms.

Valid values: name, count

Default value: name

hierarchical

(true/false) Whether to show a hierarchical or flat hyper-list of Terms. This attribute is available only for hierarchical Taxonomies.

Default value: true

When type is 'author'

show_count

(true/false) Whether or not to show the number of posts published by each author.

Default value: true

show_avatar

(true/false) Whether or not to show the author's avatar.

Default value: false

avatar_size

Description: the width (or height) in pixels of the square picture used as avatar. The show_avatar attribute has to be set to true in order for SiteTree to take this attribute into account.

Valid values: a positive integer between 20 and 512.

Default value: 60

show_bio

(true/false) Whether or not to show the biographical information set in the author's profile page.

Default value: false

order_by

Description: tells SiteTree how to order the hyper-list of authors.

Valid values: display_name, posts_count

Default value: display_name

Last update: