To edit a Zendesk layout:

If your publication has topics that contain cross-references to other publications, you should enable the Fix cross-links outside of publication scope feature in the Layout Editor before you publish to Zendesk.

It allows Paligo to resolve links in Zendesk so that cross-references between publications will work in your Zendesk articles. However, it can only resolve links to:

To enable the Fix cross links outside of publication scope setting for your Zendesk layout:

Example 10. Resolving links between Zendesk categories

Let's say you have two publications in Paligo: "Category A" and "Category B".

"Topic A" contains links to "Topic C" and "Topic E", which are topics in a different publication ("Category B").

You want to publish the "Category A" and "Category B" publications to Zendesk. In Zendesk, you create a category for each publication. You name the Zendesk categories to match the publication names, so the "Category A" publication will map to "Category A" in Zendesk.

1. You enable the fix cross links outside of publication range option in a custom Zendesk Layout:

   (The reason it is not enabled by default is for backwards compatibility).

2. You publish the "Category A" publication to Zendesk. You use your custom Zendesk layout for the publication and set the destination Zendesk category to "Category A":

3. You publish "Category B" in the same way, but set the destination Zendesk category to "Category B".

4. You check the results in Zendesk. At this point, the links from "Topic A" to "Topic C" and "Topic E" are broken. This is because the target articles ("Topic C" and "Topic E") did not exist in Zendesk when you published "Category A". However, Paligo has stored the ids for the target articles.

5. You publish both publications again, using the same custom Zendesk layout.

   (In this example, it would have been enough to re-publish "Category A", as that's the only publication that contained links to another publication. But in a real-life scenario, you might have links back and forth between multiple publications, and so you would need to re-publish each one again.)

   The links are now fixed and work as expected. This is because Paligo had stored the destination ids on the first publish. On the second publish, Zendesk contained the target articles, and the links could be resolved, even though they were in separate categories.

When publishing content to Zendesk, Paligo automatically creates extra topics for any top-level topics and sub-publications (reused publications). This helps to make sure any content in those top-level items is available in articles in Zendesk. But if you prefer, you can stop Paligo from creating this extra articles.

For a walk-through of how the extra article feature ("Create article for the section topic") works, see the example at the end of this article.

To control whether Paligo creates extra articles for the top-level content:

You can now Publish to Zendesk. When publishing, make sure you choose the Zendesk Layout that you edited. Also, use the Zendesk Preflight feature to preview the mapping. To learn more about preflight, see Zendesk Preflight Overview and Access the Zendesk Preflight Tab.

Example 11. Effect of "Create Article for the Section Topic" setting when Publishing to Zendesk

Let's say you have a publication called "Acme Building Control". Inside it, you have reused an "Air Filtering" publication and a "Fire Response System" publication. These are sub-publications. You also have a topic called "Customer Support" at the same level as the sub-publications.

Both of the sub-publications contain two topics and have a flat structure.

You set the layout option "Create Article for the Section Topic" to Disable.

When you publish, Preflight shows how the content will map to Zendesk:

Each sub-publication is mapped to a section and the articles inside the sub-publications are mapped to articles. Paligo does not create any "extra" articles, so if there is content in the "publication topics" for "Air Filtering" or "Fire Response System", it will be unavailable in Zendesk.

Note

Paligo maps the "Customer Support" topic to both a section and an article. This is because the "Customer Support" topic is at the top-level and has no child topics (level two topics). Paligo creates an extra article here, as we cannot publish to a Zendesk section that has no articles in it. (The Create Article for the Section Topic setting only applies to top-level items that have children).

You decide to change the Create Article for the Section Topic setting to Enable. As a result, Paligo maps the content differently, as shown in Preflight.

This time, Paligo creates an extra article for the "Air Filtering" sub-publication and the "Fire Response System" article. The content in these extra articles comes from the publication topics for those publications.

In Paligo, some "formal" elements contain other "nested" elements that are included automatically, such as a title or caption. For example, the example element has a title element nested within it (as well as a para element for the example text).

If you publish to Zendesk, you may want to change the appearance of the "nested" elements in your articles.

To style the "nested" elements, you first need to get Paligo to generate <span> classes for them, and then you can style the <span> classes in a CSS stylesheet:

To learn about using CSS, see Customize Zendesk articles using CSS.

Paligo has unlimited levels in the publications, so you can have as many topics and subtopics as you want. Zendesk is more restrictive, as it only has one level for articles, and this can mean that when you publish from Paligo to Zendesk, the heading levels do not match. To handle this difference, you can choose how the Paligo topic titles are mapped to the heading levels of Zendesk articles.

For example, let's say you have a top-level topic in Paligo and a second-level topic below it. Paligo could map these to Zendesk as separate articles, and the top-level topic could have an H1 heading in Zendesk, but the second-level topic would have an H2 as it was a subtopic in Paligo. This might seem strange in Zendesk, as you would have two articles but with different heading levels. By using the Follow Zendesk Heading Levels setting, you can avoid this problem.

If you are on the Paligo Enterprise plan and have an Enterprise license for Zendesk, you can map content to many different section levels. So instead of using the standard Zendesk structure of Category > Section > Article, you can have lots of sections, for example, Category > Section > Section > Section > Article.

To control the number of sections that Paligo will create:

When you publish your Paligo content to Zendesk using this layout, Paligo will map your various levels of topics to sections and articles. It will follow the mapping rules for Zendesk Enterprise layouts, where the chunck section depth defines the section levels.

The mapping for Zendesk Enterprise layouts works like this:

This is the mapping behavior with the default settings for Zendesk Enterprise layouts in place. But you can use the Chunk section depth setting (in the layout) to control how many levels of sections can be used. The default setting is 3, which provides the mapping listed above.

Example 13. Zendesk Enterprise Layout Mapping

Let's say you have an "ACME 100 Series" publication and it is going to include all the content for several products in the ACME 100 range.

At the top level, you have topics for each of the products: "ACME 100", "ACME 100X", "ACME 100XE", and "ACME 100SE".

Inside each of those, you have topics for 4 different categories of information: "Installation", "User", "Service", and "Maintenance".

Inside each category topic, you have a maximum of three levels of content. For example, in the "Installation" category, you have "Safety and PPE", then a lower level of topics, and a further level of topics inside those.

In your Zendesk Enterprise layout, you set the Chunk section depth to 4. You then go to the publishing settings, select HTML as the output, and choose your Zendesk Enterprise layout. You then select the Zendesk Preflight tab so that you can see a preview of how your content will be mapped to Zendesk:

• Top-level topics, such as "ACME 100" and "ACME 100X" become top-level sections in Zendesk.

• Second-level topics, such as "Installation" and "User" become second-level sections in Zendesk.

• Third-level topics, such as "Safety and PPE" become third-level sections in Zendesk (as the Chunk section depth is set to 4, so at level 4 the sections stop and topics get mapped to articles).

If you are used to writing content in Zendesk, it may seem strange to have a topic that maps to a section and an article. Because in Zendesk, you would not add content to a section, you would only add it to an article. But in Paligo, it is possible to have content inside top-level articles, and so if those are only mapped to a section, the content would be lost. For this reason, Paligo also creates an article, and that's where the content of the "section" topic goes.

Remember, Paligo is used for publishing to many different outputs, not just Zendesk. Having content inside a top-level topic is a common requirement for PDFs, HTML, and other outputs.

When you are planning the structure of your publication in Paligo, it is important to remember that Zendesk separates sections and articles. So in Paligo, you may have a lower-level topic set to become a section in Zendesk. But in Zendesk, that section may not appear in the same position, as sections are shown above articles, see the Example 14, “Order of Sections and Articles in Zendesk”.

Paligo cannot change how Zendesk orders its sections and articles. If you find that the order of sections and articles in Zendesk is confusing for your readers, we recommend that you either:

or

Example 14. Order of Sections and Articles in Zendesk

Let's say you have a publication with 5 levels of content and you want to use a section depth (chunk section depth) of 4.

In this example, that would mean that:

• "ACME 100" becomes a section in Zendesk as it is the top-level topic and it has lower-level topics.

• "Installation" becomes a section in Zendesk as it is the second-level topic and it has lower-level topics.

• "Safety and PPE" becomes a section in Zendesk as it is the third-level topic and it has lower-level topics.

• "Gloves", "Boots", "Ladders" and "Power Tools" become articles in Zendesk. , Although they are at the fourth-level and could become sections in Zendesk, they are mapped to articles as they do not have lower-level topics.

• "Head Protection" becomes a section in Zendesk as it is a fourth-level topic and it has lower-level topics. This is where the ordering of your content can become unusual in Zendesk, as Zendesk will display "Head Protection" as a section above the "Gloves", "Boots", "Ladders" and "Power Tools" articles.

  To avoid this issue, you can reduce the chunk section depth in the Zendesk Enterprise layout to 3. This results in "Safety and PPE" being the lowest level of section, so that all of its "child" topics appear as articles in the expected order.