How Are Excerpt Include Macros Handled?
In Confluence it is common to reuse parts of a page in other pages.
One way to do that is using the Excerpt macro to define a reusable content snippet and then, on another page, the Excerpt Include macro can be used to reference and show that reusable snippet.
In SharePoint there is nothing that compares to this function as I outlined in Sharing Content Across Pages Is Impossible.
So, when encountering those macros, how does WikiTraccs handle them?
Excerpt, Multiexcerpt
Let’s look at the source of the reusable snippets.
WikiTraccs currently handles Excerpt and Multiexcerpt explicitly.
The body content of those macros will be migrated as if it was normal page content.
The enclosing macro does matter in one regard - it has a hidden parameter. This parameter specifies if the macro is visible on the page or not.
How does WikiTraccs handle the value of the hidden parameter? That depends on the macro transformation templates for Excerpt and Multiexcerpt.
At the time of writing this, hidden Excerpt macros are skipped (the migrated page does not contain its content), but the content of hidden Multiexcerpt macros is migrated and marked as originating from a macro. This has historical reasons. The behavior can be changed by changing the macro transformation templates.
Excerpt Include, Multiexcerpt Include
Let’s look at the macros that can show the reusable content snippets defined by Excerpt and Multiexcerpt: Excerpt Include and Multiexcerpt include. Those are the two that WikiTraccs handles (at the time of writing this).
When encountering one of those Excerpt/Multiexcerpt Include macros, WikiTraccs loads the referenced page that contains the corresponding Excerpt/Multiexcerpt macro, copies its body content, and inserts it into the referencing page at the place of the Include macro.
WikiTraccs takes care of adjusting links and image references in the copied content so that they continue to work in the new context.
What WikiTraccs doesn’t do is copying images (or other attachments). If the resusable snippet contains an image, this image will be referenced also by the content that WikiTraccs copies to other pages. So, the image is not copied to other pages.
Transformation Templates
The handling of the Excerpt Include and Multiexcerpt Include macros is somewhat special in that they use the new (note: as of WikiTraccs v1.26.0) macro transformation stages builtin and postbuiltin.
When handling the Excerpt Include and Multiexcerpt macros in the builtin stage of macro transformation WikiTraccs does not yet remove those macros from the source page tree, but enriches them with the copied macro body of the corresponding Excerpt and Multiexcerpt macro on the referenced page.
Now that the macros have a body, the transformation template for the next stage, the postbuiltin stage, takes care of replacing the macro with its body content and marking it.
The excerpt-include[postbuiltin].hbs transformation template is responsible for marking the copied content with two dividers and the link to the source page.