Content by label

Content by label lists every page that carries the labels you name. Label your meeting notes meeting-notes, and one block on the team’s home page lists all of them, including the ones written next week.

Labels are short tags under a page’s title (see Labels). This block turns them into lists that keep themselves up to date, which is how a wiki gets indexes nobody has to maintain.

Insert it

Type the command at the start of a line, or after a space, and press Enter. When the list shows more than one block, use the arrow keys or click the one you want. Or choose + on the toolbar: live content blocks are at the end, under Live content. With text selected, the + menu puts the block in place of that text, so click on an empty line first.

Until you name a label in its settings, it says Name at least one label.

Each setting, live

The pages in this section carry labels, so these examples have something to find. Every one is labeled live-content, and each has one or more labels that say what kind of block it is: page-lists, this-page, includes, reports, uses-labels and needs-setup (for the blocks that show nothing until you choose a setting).

Each example below is a real Content by label block on this page, with its settings in the heading above it.

One label: uses-labels

The simplest use: every page with one label. Here, the blocks that work with labels. Beside each page, in gray, is the label it matched.

Any label: reports, includes

Pages with at least one of the labels. Use it to gather related kinds of page into one list, such as meeting-notes and decisions.

All labels: uses-labels, needs-setup

Only pages that carry every label you name, which narrows a list down. Here, the blocks that work with labels and also need a setting before they show anything.

Show 3

At most three pages. Handy for a short list beside other content, but remember the list is in title order, A to Z, not newest first.

Look in Everywhere

Matching pages from every space you can see, not just this one. Use it for an index that crosses teams, such as every page labeled incident.

Not shown here: these labels are used only in this space, so it would show the same lists as above.

Changing and removing it

While you are editing, click the block. It gets a colored outline, and a small box opens above it with the block’s name and its settings. A change shows in the block straight away; readers see it once you publish or update the page.

• Labels: one or more label names, separated by commas, such as meeting-notes, decisions. Capital letters make no difference.

• Match: Any label or All labels. Any label unless you change it.

• Look in: This space or Everywhere. This space unless you change it.

• Show: how many pages, from 1 to 100. 25 unless you change it.

When nothing matches, the block says so and names the labels, such as No pages are labeled release or api.

To remove the block, click it and press Delete or Backspace. Only the block goes: the pages, files or tasks it showed are not touched.

Good practice

• Agree on label names as a team. One spelling, used by everyone: meeting-notes on some pages and meetings on others makes two half lists.

• Label as you write. A page labeled later is a page missing from every list until then.

• Want facts, not just titles? If each page has a status or an owner you want side by side, use Page properties report instead.

Related

• Labels list shows the labels themselves, as links.

• Page properties report collects facts from labeled pages into a table.

• Label pages: clicking a label lists its pages, without a block.

• How live content works: what every live content block has in common, such as who sees what, and what happens in an export.