Zendesk Enterprise Layouts

You can use the Zendesk Enterprise layout to map topics in your Paligo publication to sections and subsections (sections within sections) in Zendesk. Paligo has a built-in Zendesk Enterprise layout that you can use or you can create your own. But please note that you can only use this layout if you are on the enterprise plan for Paligo and also have an enterprise license for Zendesk.

To use the Zendesk Enterprise layout, we recommend that you:

  1. Learn how the Zendesk Enterprise layout mapping works.

  2. Consider how Zendesk separates sections and articles.

  3. Organize your Paligo content so that your publication structure will create sections and articles in an appropriate order in Zendesk.

  4. Use the built-in Zendesk Enterprise layout or create your own. You will need to set the the Chunk section depth to define the number of section levels you want.

  5. Publish your content and select HTML as the output type and then select your Zendesk Enterprise layout. Use Zendesk Preflight to see how your content will map to Zendesk and change the mapping if needed.

Mapping for Zendesk Enterprise Layouts

The mapping for Zendesk Enterprise layouts works like this:

  • Top-level topics in Paligo are mapped to top-level sections in Zendesk.

  • Second-level topics in Paligo are mapped to second-level sections in Zendesk.

  • Third-level and lower-level topics are mapped to articles in Zendesk. if required. But with the default settings in place, only the top two levels become sections, with level three and lower becoming articles.

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.

Note

A topic can only map to a section if the topic has lower-level topics in the publication structure. For example, if a second-level topic does not have lower-level topics, it will become an article, not a section.

Example 1. 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".

Paligo publication structure. It shows the publication is called Acme 100 Series and at the top-level, it has 4 topics: Acme 100, Acme 100X, Acme 100XE, and Acme 100s.

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

Paligo publication structure. It shows the top-level topic Acme 100 has second-level topics called Installation, User, Maintenance, and Service.

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.

Paligo publication structure. It shows the second-level topic Installation has a third-level topic called Safety and PPE. The Safety and PPE topic has a fourth-level topic called Head Protection. The Head Protection topic has two fifth-level topics called Helmets and Face Guards.

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:

Zendesk Preflight showing the topics in a list on the left with tags that indicate what those topics will be in 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.

Note

If you prefer, you can control the mapping so that the top-level topics become sections, but not articles. To do this, edit the Zendesk layout and use the Create article for section topic setting (see Control whether Paligo Creates Articles for "Section" Topics).

Order of Sections in Zendesk

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).

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:

  • Reduce the chunk section depth

or

  • Reorganize your Paligo publication so that it creates an order that you find more acceptable.

    If you use your publication for multiple outputs (HTML, PDF, Zendesk, etc.,), you can create a new publication that uses the same topics. You can then use the new publication for Zendesk only, and change the organization of the topics to suit your Zendesk requirements.

Example 2. 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.

An expanded publication in Paligo. It shows that there are 5 levels of content. The levels we are interested in are level 1 Acme 100, level 2 Installation, level 3 Safety and PPE, level 4 Gloves, Boots, Head Protection, Ladders, and Power Tools. And level 5 has topics called Helmets and Face Guards. These Level 5 topics are children of the level 4 topic called Head Protection.

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.

    The content as it appears in Zendesk. The Head Protection section is shown in a separate section at the top, with a list of articles below it. The articles are called Safety and PPE, Gloves, Boots, Ladders, and Power Tools. In Paligo, the Head Protection topic is at the same level as these, not above them.

    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.