Conversion Options
The Scroll Documents conversion tool offers a number of conversion options in addition to the general content selection based on versions, variants or languages. This article will teach you about these options and how they affect conversion results.
Depending on the features enabled in your Scroll Versions or Scroll Translations managed spaces, the available conversion options may vary.
Resolve Include Macros
When converting to Scroll Documents, you'll encounter two conversion options:
“Resolve (Excerpt) Include macros in the Working version.”
“Resolve (Excerpt) Include macros across all saved versions.”
We recommend sticking to the default setting, which entails:
Not selecting "Resolve (Excerpt) Include macros in the Working version."
Selecting "Resolve (Excerpt) Include macros across all saved versions."
By following these settings, your reused page tree will be positioned outside of the Working version of your Scroll Documents, maintaining content reuse through Include macros. Meanwhile, Include macros in the saved versions will be resolved, ensuring that the content on those pages remains static.
Migrate “No Documentation” Content
Do you have any content in your space that you don't want to have as a part of your versioned or translated documentation? This could be things like reports or management pages, which you still want to move over to the new Scroll Documents managed space. Typically, these pages are located at the top level, above the root page of your documentation, and are not versioned.
We recommend categorizing all pages in your space, and adding the relevant labels before converting to Scroll Documents. To learn more read: Categorize the Pages
In Scroll Documents, by default, these pages will be moved to the Working version in your new Scroll Documents managed space. However, if you want these pages to be added to all versions of your document, you can select the option:
“Migrate 'vsndoc-no-documentation' labeled page trees to all saved versions.”
We recommend leaving this option unselected. This will store pages with the specified label at the same level as the root page of your documentation, ensuring that these pages will not be included in your documentation if you save a version.
Copy Space Permissions
When you generate a space in Scroll Documents, it's only visible to you, the converting user. This gives you a private playground to test the conversion tool without other Confluence users peeking in.
If you want to change that, you can check the "Copy Space Permissions" option. This means the generated space will inherit all the same permissions as the original space managed by Scroll Versions or Translations. It's a handy option if you want to maintain your existing access settings.
Initially, avoid copying space permissions for early tests to keep the space private. However, during the actual conversion, we recommend enabling this option. If not, you'll have to set permissions manually afterward.
Copy Inline Comments
The check box is enabled per default, meaning all your inline comments will be copied over to the generated Scroll Document.
To prevent duplicated inline comments across multiple versions, avoid checking this option during conversion.
Preserve Inline Conditional Content
Scroll Documents already supports paragraph-level conditional content in Confluence Cloud. But if you were using inline conditional content macros in Scroll Versions, you should anticipate some changes.
By default, the conversion tool will convert all your Scroll Versions conditional content macros to the equivalent Scroll Documents macros. However, it might cause some line breaks that you weren't expecting, especially if you had inline conditional content macros in your content. This is also mentioned in: Conversion with Conditional Content
Convert Page Keys
Scroll Versions assigns page keys to pages. When you convert, these page keys become Context Keys in Scroll Documents. They work quite similarly, but with a twist – you can use them in Scroll Viewport, but not within the Confluence UI.
Conclusion and Next Steps
That's a wrap on these advanced conversion options. Now you're armed with the knowledge to make the right choices when converting your content with Scroll Documents.
Whether you want to copy permissions, include inline comments, preserve inline conditional content, or convert with page keys, you can tailor the conversion to suit your needs. Just remember to consider how these options might impact your content and workflow.
Head back to Convert a Space to Scroll Documents to follow the last steps in your conversion journey. Happy converting!