Newspack Listings is a tool to help publishers create reusable lists using the Gutenberg block editor. It can be used to generate curated lists of specific items, or lists that are populated by queries. Lists can be embedded in post or page content, or anywhere core Gutenberg blocks can be used. Listing items exist as discrete, reusable pieces of content with their own standalone pages, useful for SEO purposes.

Newspack Listings is designed to be used for a wide variety of use cases, whether you want to build a directory of local businesses, a list of upcoming events, a site section for obituaries or classified ads, a series of listicles, or basically any type of content that is best displayed in list form—especially if you intend to reuse the list or items in it in various places. Edit a listing item in one place, and it will update everywhere it appears. Save curated lists as reusable blocks and drop them into various posts, pages, or widgets.

To contribute to the plugin’s development, report bugs, or make feature requests, please visit the GitHub repository.

Plugin Installation

Newspack Listings is a standalone plugin which you’ll need to install and activate in order to use:

  1. Navigate to Dashboard > Plugins.
  2. Find Newspack Listings listed in the plugins to install under Newspack.
  1. Click Install, then Activate.

If you’re not using Newspack, you’ll need to download the Newspack Listings plugin, upload it to your WordPress site, then activate it.

Plugin Configuration

After installing and activating the plugin, you’ll see a Listings menu item in your WP Admin sidebar. Hover over the menu item to see the available content types, taxonomies, and plugin settings:

The Newspack Listings admin menu.

First, click on Settings (the last link in the menu). This page contains several settings that affect the behavior of listings across your entire site. A brief rundown:

  • Permalink Settings: These settings let you define the URL slugs for each listing type. You can also optionally define a URL prefix for all listings, which will help avoid conflicts with other post types that might have the same URL slug (e.g. events).
  • Automated Directory Settings: These settings are disabled by default. If enabled, listings will be allowed to appear in category, tag, or listing post type archive pages. Details on specific settings:
    • Enable listing type archives – Enabling this setting will generate archive pages for listing post types, such as Places, Marketplace Listings, etc.
    • Enable listing category/tag archives – Enabling this setting will allow listings to appear in category and tag term archives. Note that if listings share a category or tag with other non-listing posts, they will appear together in the category/tag archive.
      • Tip: If you’d like to keep your listings separate from regular posts, create a “Directory” or “Listings” top-level category and create listings-related categories as child categories of that top-level category. Only assign the child categories to listings.
    • Show listing archives as grid – Enabling this option will show archive pages in a three-column grid layout, but only if the archive contains only listing post types.
  • Post Meta Settings: These settings let you define default behavior for showing or hiding author names, publish and modified dates, and Yoast primary categories for all listings.
  • Related Content Settings: The option to “Hide Jetpack Related Posts module” can be turned off if you want to allow Jetpack’s Related Posts module to appear on single listings.

AMP Configuration

If you use AMP on your site, you should enable AMP for all listings content types. To do this:

  1. Go to AMP > Settings in admin dashboard.
  2. Under Advanced Settings, expand the Supported Templates panel.
  3. Under Content Types, make sure the boxes are checked for all listing types (Events, Generic Listings, Marketplace, and Places):
  1. Click Save Settings at the bottom of the settings page to apply the change.

Note that there’s currently a known bug when viewing a listing page with AMP disabled. If the Newspack Campaigns plugin is active and campaigns are enabled for a post, the Campaigns plugin may conflict with certain Jetpack features, including the Jetpack Map block. If you notice a map not rendering in a listing’s content, either a.) make sure AMP is enabled for the listing type, as described above, or b.) disable campaigns on the individual listing by toggling on the “Disable Campaigns on this post or page” option.

Creating Listings

Before you can create and populate lists, you need to publish some listing content first. Think of lists as being containers that hold individual listings—all content exists in the individual listings, not the list. This lets you reuse listings across multiple lists while only needing to edit listing content in one place.

The following listing types are available to author content. These listing types are intended to provide a flexible way to organize different types of list content. Each listing type has a range of intended uses:

  • Events: These listings are tied to specific dates or times. If creating a queried list with only Event listings, the list can be optionally sorted by event date. Examples of events: upcoming board meetings, concerts in town, local elections
  • Generic Listings: These listings can be any kind of editorial content best displayed in list form. Use generic listings when you’re building a list with content that doesn’t fit into any of the other listing types. Examples of generic listings: top 10 albums of the year, holiday gift ideas, best new comedies to stream, Buzzfeed-style listicles
  • Marketplace Listings: These listings are intended to represent third-party content for monetization purposes. Currently, there are no self-service features for letting third parties purchase and/or maintain their own content, but any self-service features that are developed in the future will apply to marketplace listings only. The types of content that can be considered marketplace listings can and will overlap with other listing types, but the primary distinction is that marketplace listings are intended to be non-editorial content that exists for generating direct sales revenue. Examples of marketplace listings: classified ads, local obituaries, sponsored local business profiles, sponsored product pages
  • Places: These listings are tied to specific locations. These could be businesses or just anyplace that can be pinpointed on a map. Examples of place listings: best take-out restaurants, public parks in the area, local polling stations, COVID-19 testing sites

To create new listings, click on the listing type in the menu. This will bring you to the familiar posts-like interface, where you can add new listings or edit existing ones:

The Places interface in WP admin.

Listings must have a Published status in order to appear in lists. If a published listing is trashed or reverted to draft status, it will no longer appear in any lists it was previously added to.

Listing Content and Layouts

Listing content is built using Gutenberg blocks, just like any WordPress post or page. You can author and arrange content however you like in each individual listing. However, adding certain blocks will unlock some functionality that applies to listings only.

To help keep listing content and data consistent, Newspack Listings provides several block patterns that can be used only with the appropriate listing types. These block patterns provide prefabricated content layouts with placeholder content and empty fields to suggest the types of data that can be added to a listing. Once a pattern is added to the listing content, the blocks in the pattern can be moved around or deleted as needed.

For example, if editing a Place or Marketplace listing, you may choose to use one of several Business Listing block patterns, which provide placeholder content and data fields that could be relevant for business profiles. These include a business description, map and contact info, and business hours in a column layout:

An example business listing pattern.

To use these patterns, while editing a listing, click on the Block Inserter button in the upper-left corner of the editor to expand the block menu. Click the Patterns tab, then select Newspack Listings from the dropdown to view the block patterns available for the current listing type. Note that not all listing types support all block patterns; for example, the Business Listing patterns are only available for Places and Marketplace listings, while Event patterns are available only for Event listings, and so on.

The Block Inserter button is in the top-left corner of the Gutenberg editor, next to your site’s logo.

Note that to get the most out of these block patterns, your site needs to have Jetpack installed and connected. Without Jetpack, you will still be able to add the patterns, but some of the premium blocks in the patterns will be unusable.

Other Listing Options

Before exiting the block editor, you may want to look at a few settings that are important for listings.

Sidebar options for listings.

First, in the sidebar for your listing type, expand the [LISTING TYPE] Settings panel. Here there’s an option (OFF by default) to hide the author for this listing. If you’re using a Newspack theme, enabling this option will ensure that the author byline will be hidden wherever this listing is shown, whether it’s in a list (even if the list has enabled author display) or in the listing’s own page.

Next, under the same sidebar, expand the Categories and Tags panels. These category and tag taxonomies work similarly to Categories and Tags for regular posts, except these Categories and Tags are associated only with listings. All listing types share the same categories and tags, so there’s no need to create a “Restaurant” category for both Places and Marketplace listings, for example. Organizing listings with relevant categories and tags can help you build dynamic lists using queries (more on this later). You can manage existing listing taxonomies by visiting Listings > Categories and Listings > Tags from the main WP admin dashboard.

Lastly, under the same sidebar, expand the Excerpt panel. If you enter an excerpt here, it will be displayed whenever the listing is displayed in a list that is set to display excerpts. If this excerpt field is left blank, an excerpt will be automatically generated from the first bit of content in the listing. If the auto-generated excerpt doesn’t look good in your list, try adding your own excerpt using this option.

Creating Lists

Once you have at least one published listing of any type, you can create a list. Lists are blocks that can be added to any post or page content. To start creating a list:

  1. Edit the post or page where you’d like the list to live.
  2. In the content editor, insert a new block (either via the quick inserter or the regular block inserter). Look for the Curated List block under the Newspack block category.
The regular block inserter.
The quick block inserter.

  1. Select Curated List to add the list block to your post or page content.
  2. When creating a list for the first time, you’ll need to decide whether the list should show a query, or specific listings.
    • Specific listings mode lets you choose the exact listings to be displayed, in the order you specify. Once published, the items shown by the list will never change (unless items in the list get changed to a non-published status—these listings will no longer be shown, in that case).
    • Query mode is a more advanced mode to dynamically display listings that match the query options you set in the block. This is useful if you want the list to automatically update itself when new listings are published, or if you want the list to display many listings with “load more” functionality.
    • Once you select the list mode, you can’t change it. You’ll have to create a new Curated List block if you change your mind. This is by design, to prevent accidental loss of data.

Tip: If you’re happy with a Curated List’s content and like how it looks, you can save the list as a reusable block that can be used elsewhere.

Populating Lists in Specific Listings Mode

We’ll go through creating lists in specific listings mode first, because it’s simpler.

  1. When prompted, select Specific Listings. You’ll see an empty list like so:
An empty list in Specific Listings mode.
  1. Click the [+] inserter button to add a listing. You’ll be prompted to choose the listing type first. After choosing the listing type, you’ll see a UI to either search for a listing by title, or to select from a list of the ten most recently published listings of that type.
    • You can mix and match different listing types within the same list.
    • Listings will only be shown here if it has a “published” status and hasn’t already been added to this particular list.
Searching for a specific listing.
  1. Individual listings in specific listings mode are edited as Gutenberg blocks. Once you’ve added more than one listing, you can change the order of the listings by dragging and dropping them in place, or by clicking on the listing and using the sort buttons in the block toolbar (highlighted here in red):
  1. To remove a listing item after it’s been added, click on the listing and select the three vertical dots button in the toolbar, then click Remove block. This won’t affect the listing item itself—it will just remove it from the list you’re currently editing.
  2. Once you’re happy with the items in your list and the order they’re appearing, publish or update your post or page to make the list publicly viewable.

Populating Lists in Query Mode

If you’ve selected Query mode after adding a Curated List to your post or page, you might see some listings appear automatically. Notice that you can’t click on individual listing items to move or remove them. This is because query mode populates the list by query settings you define in the Curated List block’s sidebar. The listing items shown in the editor (and on the front-end) will automatically update as you change the query settings. It’s important to note again that query mode lists will load listings dynamically, so if new listings are published that match a list’s query settings, the list will show those new listings even if it was already published before.

The available query settings for Curated List blocks.

The available query settings are:

  • Listing Type: Lets you restrict the list to a specific listing type. Default: “Any,” meaning the list can show all types of listings.
  • Authors: If you enter one or more author names here, only listings with one of the specified authors will be shown. Default: none.
  • Categories/Tags: If you enter one or more categories or tags in these fields, only listings with at least one of the specified categories or tags will be shown. Default: none.
  • Max number of items: Sets the maximum number of listings to load at a time. If your query settings match a lot of listings, only up to this number of results will be shown. This also defines the number of additional listings loaded when the “Load More” button is enabled. Default: 10.
  • Show “load more” button: When enabled, if more listings match the query settings than the “Max number of items” option allows for, the list will show a “Load More” button until all matching listings have been loaded. Default: disabled
    • If enabled, you can also define the button label with the Load More Button Text setting. Default: “Load more listings”
  • Click Show Advanced Filters to view some more advanced query settings:
    • Sort By: Lets you choose by what criteria the listing items are sorted. Note that the available options here depend on other list settings. For example, if you set the Listing Type setting above to Event, you will see an option to sort by Event Date. Likewise, if you set the list to display authors as described below, you’ll see an option to sort by Author. If you don’t see an option here that you want, make sure the list is configured to show the data you want to sort by. Default: publish date.
    • Sort Order: Used in tandem with Sort By, lets you select whether the items should be sorted in ascending or descending order. Default: Descending, so that the default query shows listings from newest to oldest.
    • Excluded Categories/Tags: If you enter one or more categories or tags in these fields, any listings that have those categories or tags will never be shown in the list. These settings will override the Categories/Tags settings above.

List Options

Whether you’re using query mode or specific listings mode, there are a number of options available to change how the list is displayed. You can find these in the block sidebar when selecting a Curated List in the editor. All options affect every item in the list.

Here are the options and some quick notes on what they do:

List Settings

  • Show list item numbers: If ON, displays listings as numbered items. If OFF, no numbers will be displayed. Default: ON
  • Show map: If ON, a map will be automatically created inside your list with all locations of the listing items in that list. This map will update itself automatically as you add or remove listing items. Default: OFF
    • Note that for performance reasons, only up to 100 listings will be represented on the map. If your list contains more than 100 items, only the first 100 will appear on the map.
  • Show sort UI: If ON, the list will be displayed with sort by and sort order controls that let the reader sort the list. Default: OFF
    • A “Default” sort option that resets the list to the initial state is only available for lists in specific listings mode. Query mode lists will default to the sort order specified in the editor under Query Settings.
    • If the reader sorts a list after clicking the “load more” button, the list will reset to the first set of “max number of items” results.
    • Note that the sort options available in the UI depend on other list attributes. For example, the “Default” option won’t appear for query mode lists, and the “Event Date” option will only appear for query mode lists that are restricted to the Event listing type.

Featured Image Settings

  • These settings control whether and how to show a featured image thumbnail and its caption with each listing. The featured images themselves are set within each individual listing. Default setting is to show a thumbnail but no caption.

Post Control Settings

  • Show Excerpt: If ON, displays a short excerpt for each listing. This is either the excerpt set manually for that listing, or an auto-generated excerpt from the listing’s content. Default: ON
  • Type Scale: Allows you to control the size of the text in the list. Default is the base font size of your theme.

Color Settings

  • Text Color: Lets you define the color of the text in the list. Default is the base font color of your theme.
  • Background Color: Lets you define the background color of the list. Default is transparent. If changing this setting, make sure the Text Color option is something that provides enough contrast to maintain legibility.

Meta Settings

  • Show Author: If ON, shows a byline for each listing. This can be overridden on a per-listing basis by enabling the Hide author setting when editing the listing itself. Default: OFF
  • Show Category: If ON, shows categories assigned to the listing. Default: OFF
  • Show Tags: If ON, shows tags assigned to the listing. Default: OFF
Settings for featured listing status.

This feature allows individual listings to be designated as “featured” with a priority of 1–9 (default: 5). Featured listings appear before non-featured listings in all automated archive pages, and featured listings themselves are sorted in order of descending priority (9 appears before 8, etc.). You may also set an expiration date for featured status on each listing—after the expiration date passes, the featured status will automatically turn off.

Manage featured status in the Featured Listing sidebar panel when editing a listing:

Experimental Features

These features are experimental and must be turned on before they’re available. Talk to your TAM if you’re interested in using them.

Self-serve Listings

Self-serve listings features were released in an MVP state early this year. Turning on this set of features automatically enables Featured Listings on your site, and automatically generates a set of WooCommerce products that can be used to allow customers to purchase individual Marketplace listings for a specific time period, or Place listings for the duration of a subscription.

This feature set requires WooCommerce and the WooCommerce Subscriptions extension.

Settings for self-serve listings.

Once self-serve listings are enabled for your site, visit Listings > Settings to view configurable settings for your self-serve listings. These settings describe the WooCommerce products generated by the plugin, and lets you set the price of each product and premium upgrade. You can also set a period for single listing expiration, which will automatically unpublish purchased listings after the specified number of days.

Currently, the specific products and upgrades generated by the plugin are the only ones that can be purchased as part of the self-serve listings flow.

To allow customers to purchase listings, add a Listings: Self-Serve Form block to any post or page on your site:

In the block’s settings, you can specify whether the form should allow purchase of single listings (Marketplace or Event only), subscription listings (Place only), or both. If single listing purchases are allowed, you can specify the types of listings customers can purchase. In this experimental phase, the type of listing only determines the placeholder content layout for the purchased listing, and not all types have placeholder content at the moment.

Once the form is added to your site, customers can fill out the form to initiate a checkout flow to pay for their listing content:

Customer-facing checkout page for self-serve listings.

Once the customer completes the checkout process, a user account and a listing are generated to allow the user to edit their listing in the WordPress block editor. They can view and manage their purchased listing(s) and subscription(s) via the WooCommerce My Account page:

When editing a listing, customers use the WordPress block editor just like regular admin and editor users. There are several security restrictions placed on customers when editing their listings:

  • Customers can use most basic core WordPress blocks as well as some specific Jetpack business-related blocks (such as Map and Business Hours blocks). Blocks that display site meta or other sensitive information are disabled for customers.
  • Customers cannot view any page of the WordPress dashboard; they will be redirected to the My Account page if they try to enter a dashboard URL directly.
  • Customers can only preview and edit listing posts that are associated with a purchase they completed.
  • Customers can upload images to the Media Library for use in their listings, but can only see and use files that they themselves uploaded.
  • Customers cannot access featured listing settings for their listings; they can purchase “featured” status for new listings. Editors and admins can change featured settings for customer-submitted listings as desired.
  • Customers can apply existing categories and tags to their listing, but cannot create new categories or tags. We recommend you create a set of categories and/or tags specifically for self-serve listings and direct your customers to use those.
    • Tip: Consider creating a top-level category and nesting self-serve categories as child categories under it to keep things organized.
  • Customers cannot publish drafts on their own; they must submit their drafts for review. Users with admin or editor privileges must review each pending draft and publish or schedule them before they become live on the site. The expiration countdown for single listings starts only once a listing is live for the first time.
    • Tip: Use the “pending” status as an opportunity to review customer-submitted content and ensure that it’s appropriate to publish on your site, as well as assign the desired categories and tags. You can enable notifications for newly pending posts with third-party plugins such as PublishPress.
  • Listings automatically expire (revert to “draft” status) after the expiration period has passed for single listings, or as soon as the associated subscription enters an inactive state. In order to republish expired listings, customers must purchase an extension for expired single listings (which incurs the same cost as purchasing a new single listing) or renew their subscription.
Support Home

Listings Table of Contents