Skip to main content

What Happens When You Create a Branch?

When you create a branch in Paligo, the result varies, depending on:

  • The type of content you branch

  • The branching options you choose

  • Where the branch is created. Branching a topic from the Content Manager is different from branching a topic from the Structure View.

In the following sections, we explain what happens when you create a branch. We also explain how Paligo handles content reuse, cross-references, and images for branched content.

New Publication Branch

You can Create a Publication Branch. When you do this, Paligo will:

  • Create a branch of the publication

    Original publication and branched version of publication shown in Content Manager.

  • Let you choose how you want reused publications to be handled.

    With automatic branch creation, Paligo will create branched versions of any reused publications, but only for those at the top-level of the original publication. If there are reused publications that also contain lower-level reused publications, those lower-level ones will not be branched automatically.

    Branched publication structure contains other publications. These other publications also have branches created for them.

    If you do not use automatic branching, your branched publication will use the original versions of any reused publications (sub-publications).

  • Let you choose how you want reused topics to be handled.

    If you choose to use automatic branching, Paligo will create a branched version of every topic in the publication. Any changes you make in the branched topics will not affect any other branches or publications.

    Branched publication structure shows the publication has forks that point to branches of topics.

    If you do not use the automatic branching, Paligo will create a branch of the publication only, not its topics. The branched publication will reuse the original versions of the topics.

    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.

New Topic Branch from a Publication Fork

If you Create a Fork Branch for a topic, Paligo will:

  • Create a branch of the topic

  • Set the publication fork to link to the branched version of the topic instead of the original version of the topic.

    branch-topic-from-fork.jpg

  • Check the original topic for reused text fragments. These text fragments will also be reused in the branched version of the topic, so the IDs will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.

  • Check the original topic for text fragments that are not reused. These are "regular" paragraphs and content structures and Paligo will give these new IDs in the branched version. So if you change them in the branched version, your changes will not affect the original branch.

  • Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.

  • Check the original topic for references to other files, such as images. The branched version will use the same files as the original version. Paligo will not create a new, separate file. For example, if the original topic contains an image, the branched version will contain the same image (they both reference the same image file in the Media library). If you edit the image, those changes will apply wherever that image is used.

New Topic Branch from a Topic

If you Create a Topic Branch in the Content Manager (rather than from a fork in the publication structure), Paligo will:

  • Create a branch of the topic

    The branch is a stand-alone branch and is not used in any publications. Any publications that use the topic will continue to use the original version.

    Publication structure uses the original version of a specifications topic. In the Topics folder, there is the original specifications topic and a branch of the specifications topic.

  • Check the original topic for reused text fragments. These text fragments will also be reused in the branched version of the topic, so the IDs will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.

  • Check the original topic for text fragments that are not reused. These are "regular" paragraphs and content structures and Paligo will give these new IDs in the branched version. So if you change them in the branched version, your changes will not affect the original branch.

  • Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.

  • Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.

  • Check the original topic for references to other files, such as images. The branched version will use the same files as the original version. Paligo will not create a new, separate file. For example, if the original topic contains an image, the branched version will contain the same image (they both reference the same image file in the Media library). If you edit the image, those changes will apply wherever that image is used.

Reused Content in Branches

If you have reused content in your publications and topics, this is how Paligo will handle it when you Create Branches:

  • Text fragments

    Paligo will check the original topic for any text fragments that are reused. These text fragments will also be reused in the branched version of the topic, so the ids will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.

    In the branched version, Paligo will only give new ids to those text fragments that were not reused in the original version.

  • Components

    Paligo will check the original topic for any reused components, such as a topic that has been inserted into another topic. These components will also be reused in the branched version. If you change them in the branched version, those changes will also apply in all of the other topics where those components are used.

  • Reused publications inside a publication

    If you branch a publication that contains reused "sub publications", you can set Paligo to automatically create branches for the reused publications.

    For example, if you have a "Documentation" publication that contains "Getting Started" as a sub-publication, you could branch "Documentation" and set Paligo to automatically branch the "Getting Started" sub-publication too. The resulting "Documentation" branch would contain the branched version of the "Getting Started" sub-publication.

    For more details, see Create Branches.

Cross-References in Branches

When you Create a Fork Branch, Paligo recognizes that the branch has a relationship with the original version of the topic and other branches from that topic. As a result, Paligo is able to resolve any cross-references between the original topics even when these topics are branched into new topics.

When you add a cross-reference to a topic, you should normally add the link to the origin topic, not the fork (topic reference inside a publication). Paligo can then resolve the cross-references even if topics have been branched multiple times. There is one exception to this rule, which applies in a particular scenario when publishing to external systems such as Zendesk, SalesForce, and ServiceNow (see the note below).

To learn how to add cross-references to topics, see Add Cross-Reference to Topic.

Example 1. Example of using cross-references to branched topics

Let's say you have an "Installation" topic and you branch it.

Then, in a "Getting Started" topic you need to add a cross-reference to the branched version of the "Installation" topic.

For that, you add a link to the origin topic (component) "Installation", not its publication fork.

New cross-reference dialog shows Installation topic and a branched version of the Installation topic. An arrow points to the original version.

When you publish, Paligo processes the cross-reference and looks for the target. It knows that "Installation" and "Installation (branch 1)" are different versions of the same topic, so as long as there is a branch of that topic in the publication, it can resolve the cross-reference.

A publication structure showing that the Installation topic is included in the publication.
A publication structure showing that a branched version of the Installation topic is included in the publication.

Cross-references will work even if you branched topics as long as any branch of that topic exist in the publication.


Note

Cross-reference a publication "fork" to the topic instead of the actual topic if both of the following apply:

  • You publish multiple publications to different categories in an external support platform, such as Zendesk

  • You have reused the same topic in multiple publications, and those are being published to separate categories

In this specific scenario, you need to cross-reference to the fork in the publication instead of the topic. This is needed so that Paligo can resolve the link and maintain the mapping of the content when it is published to the external support platform.

Images in Branches

When you Create Branches, Paligo checks to see if the original version of the topic contains images. If it does, Paligo will keep the same references to the image file in the branched version. Paligo will not create a branched version of the image file.

If you edit an image, those changes will apply wherever that image is used, and that includes other branches.

If you want a branched version of a topic to use a different image, add the new image to the media library and insert it in the branched topic.

To learn how to add images, see Add an Image.

A "fork" is a special type of link between a publication and its content. This means that it's not the topic or subpublication itself, but a reference (link) that is used in a publication. Learn more, see Forks.

fork.png

  1. Fork, only a reference (link) to the actual topic

  2. Actual origin topic, where you write your content