Skip to main content

Create Branches

In Paligo, you can create branches of your publications and topics. Each branch is a copy, but can also be merged back into earlier branches. This is useful for creating different versions of content for similar products and also for having concurrent versions of your documentation. For more examples of use cases for branching, see Branching.

Note

We recommend that you branch topics from inside a publication rather than branch topics independently.

Create a Publication Branch

To create a branch of a publication:

  1. In the Content Manager, find the publication and select its options menu ( ... ), and then New branch.

    Paligo displays the Create Branch dialog.

    Create branch dialog. It has a label field and auto-branching settings for publications and topics.

  2. Enter a name for the Label. This will appear in a box next to the name of the publication in the Content Manager and elsewhere. We recommend that you add a descriptive Label so that it is easy for other users to tell the difference between different versions of the same publication.

    Example of a label. The label is shown as a gray box next to the publication title, with the label text inside the box.

    The Label setting is optional. If you do not want to use a label, leave it blank.

  3. In the Auto-branching section, choose whether Paligo should create branches for any sub-publications as well:

    Clear the Publications box if your publication:

    • Contains reused publications (sub-publications), and you want to make changes to some of them without affecting the originals.

    • Contains reused publications (sub-publications) and you do not want to make changes to them.

    • Does not contain reused publications (sub-publications).

    When you clear the box, Paligo reuses the sub-publications and does not branch them. If you make changes to the sub-publications, those changes will also affect the same sub-publications in other branches. To make changes that do not affect other branches, create a branch of the sub-publication first, and then work on the branched version.

    Check the Publications box if your publication:

    • Contains reused publications (sub-publications), and you want to make changes to all of them without affecting the originals.

    When you check the box, Paligo will create a branch for your selected publication and will also create new branches for any sub-publications inside it. Any changes you make to the sub-publications will not affect other branches.

  4. In the Auto-branching section, choose whether Paligo should automatically create branches for the topics.

    Clear the Topics box if your publication reuses topics.

    auto-branching-topics-off.jpg

    When you branch the publication, it will continue to use the same topics, so any changes you make to those will also affect other branches. If there are topics you do need to change, you can branch those topics from the publication forks independently.

    Check the Topics box if your publication does not have much (if any) reuse of topics, and you want to use the new branch as a "work in progress" version. When you branch the publication, it will use entirely new branched versions of the topics, so any changes you make to them will not affect other branches.

    Note

    Auto-branching of topics is designed for particular scenarios, and in most cases, we recommend that you leave it disabled (clear checkbox). This is because auto-branching can result in unnecessary branches of topics where reused topics would be more appropriate.

  5. Select Create.

    Paligo creates a branched version of your publication. It is shown next to the original version of the publication in the Content Manager.

    The original version has a gray branch symbol. Branches have a blue symbol with a number. The number represents the version. For example, in the following image, "Getting Started" version 2.1 has a branch symbol and 1, as it is the first branch of the original "Getting Started" topic.

    Branch icons. Gray for a publication that has a branch, blue for a publication that is a branch.

    For consecutive branching (set in the System Settings), the numbering will also show the origin branch number in parentheses.

    branch-icons.jpg

    In the example shown, the "Getting Started" with the "UPDATE" label has 2 and (1) to show it is the second branch to stem from the main "Getting Started" topic and is a branch of the first branch (1).

You can now work on the content in your branched version.

If your branched publication has the same topics as the original, then the changes you make will affect those topics wherever they are used.

If you branched the publication and its topics, the branched topics will be independent of the originals. You can make changes to the branched topics without affecting the original version or other branches. But note that if a topic reuses a text fragment, that fragment is always reused, even in branched versions of the topic.

To find out more, see What Happens When You Create a Branch?.

Create a Forked Topic Branch

We recommend that you create branches of topics from inside the publication, as described in this section. This is because when you branch from a publication's "fork", the branch uses the same fork ID and this is important for resolving cross-references and when mapping to external systems such as Zendesk, SalesForce and ServiceNow.

Note

There are alternative ways to create a branch of a topic. You can get Paligo to create a branch for every topic in a publication automatically, and this will keep the same fork ids too, Create a Forked Topic Branch.

You can also create a topic branch directly from the topic. This is completely independent of any publications, see Create a Stand-Alone Topic Branch.

To create a branch from inside a publication:

  1. In the Content Manager, find the publication that contains the topic you want to branch. Expand it so that you can see the topics that are included in the publication. The topics you see here represent the "forks" in the publication - these are links from the publication to the topics that it references.

    Content Manager showing a publication. The publication is expanded to reveal the topics that it references.

  2. Select the options menu ( ... ) for the topic that you want to branch, then select Branching > New branch.

    new-branch-topic-from-pub.jpg

    Paligo creates a branch of the selected topic. The publication is updated automatically so that it references the branched version of the topic instead of the original version.

    Publication is updated automatically to reference the branch of the topic. The branched topic has a branch icon.

    Paligo stores the branched topic in the same folder that contains the original version of the topic.

    new-topic-original-and-branch.jpg

    The main original version has a gray branch symbol. Branches have a blue symbol with a number, and the number represents the version. For example, in the image shown, "Quick Set Up" is the main, original version, so it has a gray branch symbol. The branched version has a blue branch symbol with the number 1, to show it is the first branch to be created from the main original topic.

    For consecutive branching (set in the System Settings), the numbering will also show the origin branch number in parentheses.

  3. Select the options menu ( ... ) for the branched topic that you have created. Then select Branching > Edit Label and enter some text for the label. We recommend that you add a label that makes it easy to tell the difference between this branch and the original branch.

    Adding a label is optional.

You can now work on the content in your branched version.

For branched topics, you can change the content in the branched version without affecting the original version or other branches. But note that if a topic reuses a text fragment, that fragment is always reused, even in branched versions of the topic.

To find out more, see What Happens When You Create a Branch?.

Create a Stand-Alone Topic Branch

When creating a branch directly from a topic in the Content Manager, it becomes a "stand-alone" branch that is not used in any publications. The result is that the publication will continue to use the original version of the topic and the branched version will exist in the Content Manager. This makes it possible work on it, even if the publication is to be published during the update. Once you have done the required changes, you merge it with the main branch and it will replace the old version in the publication.

To create a stand-alone branch of a topic:

  1. Find the topic in the Content Manager.

    You need to find the topic, not the "fork" from a publication to a topic. A topic appears with a white file icon and is on its own. A "fork" appears as a gray icon and is always shown as being inside a publication.

    new-topic-original-and-branch.jpg
    Publication is updated automatically to reference the branch of the topic. The branched topic has a branch icon.

    Topics are independent and have a white file icon (left). "Forks" are inside publications and have a gray file icon (right).

  2. Select the topic's options menu ( ... ) and then select Branching > New Branch.

    Paligo creates a branch of the selected topic.

  3. Select the options menu ( ... ) for the branched topic that you have created. Then select Branching > Edit Label and enter some text for the label. We recommend that you add a label that makes it easy to tell the difference between this branch and the original branch.

    Adding a label is optional.

You can now work on the content in your branched version.

For branched topics, you can change the content in the branched version without affecting the original version or other branches. But note that if a topic reuses a text fragment, that fragment is always reused, even in branched versions of the topic.

To find out more, see What Happens When You Create a Branch?.

In this section:
See also: