Excerptory documentation
Excerptory maps the content you reuse in Confluence Cloud: native Excerpt and Insert excerpt macros, synced blocks, and Excerptory's own Snippet and Insert snippet macros.
Get started
- Install Excerptory from the Atlassian Marketplace.
- Open Apps > Excerpt library, go to Scan spaces, select your spaces and click Scan. Scans only read pages. Large spaces take a few minutes; click Refresh to see progress.
- From then on, the library updates itself whenever a page is created or edited.
You can scan any space you can view. The library always shows each person only the pages they can open.
The Excerpt library
Open it from Apps > Excerpt library, or from a space's sidebar to start filtered to that space.
- Library: every excerpt, snippet, synced block and MultiExcerpt macro, with its source page, when it last changed, and how many pages use it. Search by name, page or text; filter by type or space. A space filter also shows sources from other spaces that are used in this one.
- Details: the pages that use a source, which ones are in a table, which ones came through Insert snippet, and which ones to review because the source changed after they were last edited.
- Problems:
- Broken: an include points at a page that no longer exists (or was renamed), or at an excerpt name the source page no longer has.
- Warning: two excerpts on one page share a name (Confluence only shows the first one); a hidden excerpt nobody includes; an Insert snippet without a value for one of its variables; a synced block whose source is not in any scanned space.
- Info: an unused excerpt; pages to review after a source changed.
- Export CSV: one row per source and page that uses it, ready for a spreadsheet.
Rename an excerpt everywhere
In the library, open Details on a named native excerpt, type the new name and click Rename everywhere. Excerptory renames the excerpt on its page and updates every Insert excerpt (and Insert snippet) that uses it, as you. Pages you can't edit are listed so you can ask their owner. Each change is a normal page version.
Names can't contain : | " < or >. A page can't have two excerpts with the same name.
The Reuse button
Every page has a Reuse button in its byline. It shows what this page shares and where each piece is used, what this page reuses from elsewhere, and any problems on this page.
Snippets with variables
- Insert Snippet (Excerptory) on a page and type the content inside it. Use
{{name}}for anything that should change per page, for example{{product}} includes {{seats}} seats. - Name it in the macro settings, optionally describe it, and optionally hide it on its own page.
- On another page, insert Insert snippet (Excerptory), search for the snippet, fill in the values and click Insert. Use Insert snippet inline inside a sentence or table cell.
Snippets are linked by id, so renaming a snippet or moving its page never breaks the pages that
use it. Insert snippet also works with your existing named native excerpts. A value left empty
shows as {{name}} on the page and is listed in Problems.
Permissions and privacy
- Included content is read as the person viewing the page. Someone who can't open the source page sees a short note, not the content.
- The index stores page ids, titles, excerpt names and a 160-character preview, in Atlassian's Forge storage for your site. Nothing is sent outside Atlassian.
Limits
- Synced blocks are mapped but can't be created by apps (Atlassian has no API for it yet). Synced blocks used in Jira are not mapped.
- Headings inside included content don't appear in Confluence's Table of Contents. This is a Confluence limitation that also affects native includes (CONFCLOUD-72449).
- Pages in spaces that were never scanned appear once they are edited.
- MultiExcerpt macros are mapped read-only; rename them in MultiExcerpt.