Heading numbering with multiexcerpts and included pages

[Craig Senior]

Given:

• Confluence Server 7.17.4
• We include multiexcerpts into pages with numbered headings. These pages can be used standalone.
• We include pages with numbered headings into larger pages to render to PDF. The use case is the reader opens a single PDF and can search or navigate with bookmarks.

Problem:

In the rendered 300-page PDF, we have duplicate H1 headings in sections that should be subordinate, i.e. instead of H1, H2, H3, we have H1, H1, H2:

• H1 from the page title
• H1 from the Heading 1 headings on the page

Desired behaviour for the rendered PDF:

• Render page titles as H1
• Render Heading 1 from included pages as H2, Heading 2 as H3, and so on. If an included page was rendered on its own, then H1 needs to render as H1, and so on.

Troubleshooting:

The desired behaviour feels obvious, so the answer might be staring us in the face. Maybe there's a settings or combination of settings that we overlooked. What we looked at:

• PDF export macro settings
• export template settings (I don't personally have access to this, so I'm uncertain what was attempted)
• Numbered Headings macro settings
• Include pages by label macro settings

Workarounds:

• Render each included page as its own PDF and compile them into one PDF, using Adobe DC. Create a chapter page for each included page, tolerating duplicate page and heading numbers.
• Export to Word, allow Word's heading numbering to renumber everything and regenerate the Table of Contents; and export from Word to PDF.
  This failed because some images that rendered to PDF did not render to Word, I assume because of a defect in the Export to Word macro.
• The Multiexcerpt Include macro has the option:
  

  Use MultiExcerpt Include Page Context - Use the MultiExcerpt INCLUDE page context instead of the MultiExcerpt page context to render the body of the included MultiExcerpt. This is only used in special cases.

  The Include Page macro has no such option.
  The Include Content by Label macro has no such option.
  
  Assuming Use Multiexcerpt Include Page Context works, retrofit all page inclusions to multiexcerpt inclusions with the Include Page Context option set.

• The solution I chose: Retrofit the entire set of pages, changing heading levels so that the set of pages and excerpts fits together without depending on Confluence or its macros to renumber correctly as pages and multiexcerpts are combined. This took some one-time effort, but now that it's defined, it can be carried forward to subsequent releases of the set.
• Don't try this at all. Get the target audience to accept separate documents.

Maybe someone here knows exactly what to do, "Oh yes, just do X..."