Shortcode References

Shortcode

AlphaListing includes a shortcode so you can render the directory without editing templates. The simplest usage outputs the default page listing:

[alphalisting]

Displaying different content types

• Specific post type:

[alphalisting display="posts" post-type="post"]

• Filter posts by taxonomy and term:

[alphalisting display="posts" post-type="post" taxonomy="category" terms="my-term-slug"]

• Show only child pages of a specific page:

[alphalisting display="posts" post-type="page" parent-post="24"]

• Include descendants of any depth for a page:

[alphalisting display="posts" post-type="page" parent-post="24" get-all-children="yes"]

• Display taxonomy terms instead of posts:

[alphalisting display="terms" taxonomy="category"]

• Limit taxonomy terms to a branch of the tree:

[alphalisting display="terms" taxonomy="category" parent-term="42"]
[alphalisting display="terms" taxonomy="category" parent-term="my-parent-slug" get-all-children="yes"]

Customizing the alphabet

• Override the alphabet:

[alphalisting display="posts" alphabet="Aa,Bb,Cc,Dd,Ee,Ff,Gg,Hh,Ii,Jj,Kk,Ll,Mm,Nn,Oo,Pp,Qq,Rr,Ss,Tt,Uu,Vv,Ww,Xx,Yy,Zz"]

• Append numbers to the alphabet:

[alphalisting display="posts" numbers="after"]

• Prepend numbers before the alphabet:

[alphalisting display="posts" numbers="before"]

• Group all numeric items together:

[alphalisting numbers="after" group-numbers="yes"]

• Create grouped ranges of letters:

[alphalisting grouping="3"]

Adjusting the layout

• Change the number of columns:

[alphalisting columns="4"]

• Set the column width and the gap between columns:

[alphalisting columns="4" column-width="18em" column-gap="2em"]

Splitting the letter links onto another page

Render only the A–Z navigation, pointing each letter at the page that holds the full listing:

[alphalisting return="letters" target="24"]

All shortcode arguments are optional—omit any attributes you do not need.

Shortcode options

Fine-tune the shortcode with the following attributes. Unless otherwise noted, each attribute accepts a single value.

Attributes that accept a true/false value recognize true, yes, y, on, and 1 as true. Anything else, including an omitted value, counts as false.

Common options

• display: Choose whether to list posts (posts, default) or taxonomy terms (terms). Any other value falls back to posts.
• numbers: Show numeric headings before (before) or after (after) the alphabet. Defaults to hide. Any value other than before or after hides the numbers.
• grouping: Group letters together. Provide a number greater than 1 to create ranges (for example, 3 produces A-C, D-F, and so on). Set to numbers to group numerals into 0-9. Invalid values disable grouping. Note that a grouping above 1 also groups the numbers into 0-9 unless you set group-numbers yourself.
• group-numbers: Collect all items that start with a numeral into a single 0-9 section. Only has an effect when numbers is before or after. Defaults to false.
• symbols-first: Move the # heading—the bucket for items that do not start with a character in the alphabet—ahead of the alphabet instead of after it. Defaults to false.
• alphabet: Override the alphabet used for headings. Provide a comma-separated list where the first character in each group becomes the heading. When omitted, AlphaListing uses a locale-aware default or a translation from GlotPress.
• back-to-top: Accepts true or false to display/hide the "back to top" links. Defaults to true.

Layout options

• columns: The number of columns the listing is split into. Accepts a whole number from 1 to 15. Defaults to 3. Values outside the range are clamped, and non-numeric values fall back to the default.
• column-width: The target width of each column. Accepts a number with a px, em, rem, %, or ch unit—for example 18em. Defaults to 15em. Pixel values are capped at 1200px, and % and ch values at 100. Unrecognized values fall back to the default.
• column-gap: The gap between columns. Accepts the same units and limits as column-width. Defaults to 0.6em.

Post listing options

Used when display="posts" (the default).

• post-type: Comma-separated list of post-type slugs to include. Defaults to page.
• parent-post: Only show posts that are children of the given parent post ID. Combine with get-all-children="yes" to include the full hierarchy. Defaults to unset.
• get-all-children: Include descendants of any depth rather than only direct children. Applies to parent-post here and to parent-term in a term listing. Defaults to false.
• exclude-posts: Comma-separated list of post IDs to hide. Defaults to unset.
• taxonomy: When filtering posts by terms, provide the taxonomy slug here. Defaults to unset.
• terms: When filtering posts, provide the term slugs or IDs. Requires the taxonomy attribute and accepts a comma-separated list. Prefix a slug with ! to exclude that term instead. Defaults to unset.
• exclude-terms: Comma-separated list of term IDs whose posts should be hidden. Uses the taxonomy given in taxonomy, or category when that is unset. Defaults to unset.
• group-by: Accepts last-word to group and sort posts by the last word of each post title. Any other value leaves the default title ordering in place.
• ignore-articles: Accepts en, es, fr, or it to sort posts by the first word after a leading article. The full title is still displayed. Defaults to unset.

Term listing options

Used when display="terms".

• taxonomy: Comma-separated list of taxonomy slugs to display. Defaults to unset.
• terms: Only include specific terms, given as slugs or IDs. Requires the taxonomy attribute and accepts a comma-separated list. Prefix a slug with ! to exclude that term instead. When the list contains anything to include, exclusions are ignored. Defaults to unset.
• exclude-terms: Comma-separated list of term IDs to hide. Ignored when terms names any terms to include. Defaults to unset.
• parent-term: Restrict the listing to terms descending from this term, given as a slug or an ID. Combine with get-all-children="yes" to include deeper levels. Defaults to unset.
• get-all-children: Include descendants of any depth rather than only direct children. Defaults to false.
• hide-empty-terms: Suppress terms that have no associated posts. Defaults to false.

Internal options

These values are available for completeness and rarely need adjusting.

• return: Choose whether the shortcode returns the full listing (listing, default) or just the letter navigation (letters).
• target: The page the letter links point at, given as a post ID or a URL. Use it with return="letters" to place the A–Z navigation on a different page from the listing itself. Defaults to unset, which links within the current page.
• instance-id: The HTML id used for this listing's anchors, so the letter links and the "back to top" links land in the right place. Set it when you put more than one listing on a page. The value is sanitized for use in an HTML id. Defaults to an automatically generated value.
• parent-term-id: The same as parent-term, but only accepts a numeric term ID. parent-term already accepts an ID, so prefer that one.

Deprecated options

• hide-empty: Replaced by hide-empty-terms in 4.0.0. It still works, but it logs a deprecation notice—switch to hide-empty-terms.