Import or Export Content
Paligo lets you import existing content in a number of formats, including: HTML, DocBook, DITA, Microsoft Word, Paligo Export Format (XML), Atlassian Confluence, MadCap Flare, Zendesk Guide (help center) and more. Some can be imported directly, but in other cases, you will need to first convert the content into a different format and then import that.
There are always some limitations regarding what can be imported from one format to another and some import formats will work better than others. In general, the more structured the legacy format, the more complete the import will be.
When an import is too big, Paligo recommends to divide the import in smaller packages. Variable sets that have been included in previous imports, will get duplicated, unless a variable set ID is entered in "Match with existing variable set", see Use the Import Wizard and Find a Variable Set ID.
However, you can only match one variable set, so if there are multiple in the import, the others will still be duplicated. Therefore it might be a good idea before exporting the content, to either:
-
Merge the variable sets into one
-
To use one variable set per import package
 |
Warning
An import is not the same as a migration, but a tool that speeds up the process of migration significantly. But every import must always be checked manually to make sure no content is missing or incorrect in any way.
Tip
When importing content, Paligo will not automatically create a snapshot of the imported content. Paligo recommends you to always create a Create Snapshot in Resource View of the imported content, to have an archived version to compare with the changes you make.
A prerequisite for a successful import is that the legacy format is fairly well-structured. It should also be noted that if you're moving from unstructured and non-topic-based content (such as Word), you are likely to want to rewrite quite a bit of the content to make it topic-based, reusable, and so on. So while the import functionality works very well, you should always consider carefully what is the best strategy for your content.
If your content is well-structured and divided into topic-like sections already, you may gain a lot from an import, saving you time on migration. But if a lot of rewriting is necessary anyway, the gains will be smaller, and importing in such a case might not even be a good idea at all.
"Smart Import" means that Paligo doesn't just blindly import all your content, it will create reuse directly.
It can intelligently detect in many cases whether the same content has already been imported. That is, it will recognize if a topic or image is identical to one previously imported. So you will not get unnecessary duplicates, and your work on reuse may begin already during import.
For Paligo to recognize topics and images they need to be identical. But if they are, it will automatically ignore the topic or image and instead reuse the one already in the system.
You can import many different types of content into Paligo. Some formats can be imported directly, whereas others require an indirect import where you convert the content into a different format before you import it into Paligo.
-
Direct imports means that you can Use the Import Wizard without converting the files.
-
Indirect imports means that you have to use an external application to convert the content to a format that Paligo supports for direct imports before you can Use the Import Wizard.
Tip
Always check the existing tool for output or conversion formats. For example, if you want to import Adobe FrameMaker content, you could use FrameMaker to create an XHMTL version and then import the XHTML content into Paligo.
 |
The table below describes the different import formats. Each format has its own preparations.
Tip
It is also possible to have the import customized for your needs. Contact support for more information.
|
Import format |
Description |
|---|---|
|
Paligo Export File (PEF) |
Direct import in Paligo import wizard. This XML format is used for backups among other things, see Import Paligo Export File (PEF). |
|
Author-it |
Export to XHTML and use the Author-it format option in the Import Wizard. Prepare the content, see Import from Other Formats. |
|
Confluence |
Direct import in Paligo import wizard. The import works with an HTML Confluence Space export and other XHTML imports. Prepare the content, see Import from Confluence. |
|
DITA (ditamap) |
Direct import in Paligo import wizard. Prepare the content, see Import from DITA. |
|
DocBook 4 or 5 |
Direct import in Paligo import wizard. Prepare the content, see Import from DocBook. |
|
FrameMaker |
Export to XHTML and use the Confluence format option in the Import Wizard. Prepare the content, see Import from Other Formats. |
|
HTML |
Direct import in Paligo import wizard. Prepare the content, see Import HTML (Single File) and Import HTML (Multi File). |
|
Help & Manual |
Direct import in Paligo import wizard. Prepare the content, see Import from Help and Manual. |
|
MadCap Flare |
Direct import in Paligo import wizard. Prepare the content, see Import from MadCap Flare. |
|
MS Word |
There are three options when preparing import from Microsoft Word, see Import from Microsoft Word. |
|
RoboHelp |
Export to XHTML, HTML, DITA or MS Word and use the corresponding format option in the Import Wizard. Prepare the content, see Import from Other Formats. |
|
Swagger OpenAPI |
Direct import in Paligo import wizard. Prepare the content, see Import Swagger OpenAPI. |
|
Zendesk Guide (Help Center) |
Direct import in Paligo import wizard. Prepare the content, see Import from Zendesk. |
|
Other formats:
|
Export to XHTML, HTML, DITA or MS Word and use the corresponding format option in the Import Wizard. Prepare the content, see Import from Other Formats. |
Paligo has an import wizard that makes it easier to import content from other formats, including DITA, MadCap Flare, Confluence and Microsoft Word. The settings are grouped in two tabs: General options and Custom options. Some settings and preparations differ between the import formats.
During the import, Paligo will:
-
Automatically detect if several of the sections you are importing are identical. If it finds any, it will import the topic once and will then reuse the topic rather than import the same section several times. This is more efficient as, ideally, content should exist once in Paligo, and then that single instance is reused wherever it is needed.
-
Detect errors in the structure. If you get a warning about incorrect structure when you import content, try checking the Ignore warnings on import validation box. It is available for all formats apart from Paligo Export Format (PEF). When this feature is enabled, Paligo will attempt to fix any invalid structures that it finds during the import.
-
Import your content and separate it into topics. These topics are then organized into a publication and project, with the same structure as the original version of the content.
 |
Tip
The necessary preparations before an import differs between the import types, see Import Types.
To import content to Paligo:
-
Prepare the content and put it in a folder and zip it.
Note
There must only be one main content file in the folder, such as
index.htmlfor HTML format. Images can be in folders or not, as long as they are in the same zipped folder and the references to them are correct.The preparations might differ depending on the Import type.
-
Select the Dotted menu (...) for the documents folder in the Content Manager.
-
Select Create folder.
-
Enter a folder name and confirm it with the checkmark.
-
Select the Dotted menu (...) for the new folder in the Content Manager.
-
Select Import content.
-
Select the Import type from the menu.
-
Select OK.
-
Select the zip file to be uploaded.
-
Set your preferences for the General options tab:
-
Try to match components with existing components
Check this box if you want Paligo to recognize components that are identical to components that already exist in Paligo. When this is enabled, Paligo will not import content that already exists and will reuse the existing content instead. We recommend that you check the box so that your imports are more efficient and take advantage of Paligo's content reuse capabilities.
-
Import admonitions as separate components
Paligo recommends that you check this box if you know you have many identical admonitions (notes, warnings and more). But if most are unique, leave it unchecked.
-
Ignore warnings on import validation
In most cases, Paligo recommends that you check this box unless you have problems when trying the import. Paligo will usually fix minor problems automatically during the import process. If you disable this feature, Paligo will reject any invalid XML, display a warning message and stop the import process.
Note
This option is not shown for Paligo export file (PEF) imports. This is by design.
-
Schema max depth level
Only available for Swagger OpenAPI
This number represents the level of schema objects that can be included in the code samples in your documentation.
For example:
-
Schema max depth level = 1. Paligo does not use referenced schema objects for the samples. The name of the referenced schema is included, but its content is not shown.
Max depth 1: { "company" : {} } -
Schema max depth level = 2. Paligo shows the content of the referenced schema object. If that referenced object includes references to other schema objects, only the names of those objects are shown.
Max depth 2: { "company" : { "name" : "Paligo", "country : "Sweden, "address" : {} } } -
Schema max depth level = 3. Paligo shows the content of two levels of referenced schema objects. If the second level of referenced schema objects include references to other schema objects, those references are by name only.
Max depth 3: { "company" : { "name" : "Paligo", "country : "Sweden, "address" : { "street" : "Street Name 123", "postcode" : "1234", }, } }
-
-
Code snippet languages
Only available for Swagger OpenAPI
These are the languages that you want to use for code samples in the published output. They will appear as options at the top of the sample code part of the API documentation, if you publish using the API style layout. When a reader selects an option, the code sample changes so that it provides the code in the selected language. For example, if the reader selects JavaScript, the JavaScript code samples are shown.
1 = Language buttons at the top of the API documentation (published output), 2 = The code sample.
Tip
To choose which languages are included in your import, select an empty part of the field to display a drop-down menu. Choose the language(s) your content includes, for example, PHP.
If you want to remove a language, select the x icon on the blue button for that language.
-
-
Set your preferences for the Custom options tab:
-
Title prefix
Use this setting if you want to mark your imported topics with a prefix. Enter the prefix in the field. If you do not want a prefix, leave the field blank.
-
Folder numbering
Enable this setting to add sequential numbering to the folders for your imported content.
-
Max folder levels
Use to control the maximum number of folder levels Paligo will create for your imported content. By default, Paligo will create a folder structure that matches the structure of your import content down to the second level. For example, if you have a manual with chapters and subsections, the import will create a folder for each "chapter" and the first level of subsections.
The default value is set to 1. It means that each group of topics will be in one folder. In the image below, the topics addPet, deletePet, findPetById and findPets are all in a single folder named as
2. Default. If you set the value to 2, the content would be organized so that each topic is in its own folder.You can increase the number of folder levels to whatever number you need for your content. Paligo will create a new folder for each level as long as there is content at that level in the import.
To the left the max folder level is set to 1 (default).To the right the max folder level to 2.
-
Match with existing variable set:
Paligo can create variable sets from DITA, MadCap Flare, Paligo Export File (PEF) and DocBook 5.1 imported content. This setting only applies to those.
-
First time you import the content, leave this field blank. Paligo will create a variable set for your content.
-
Been imported before or it already exists in Paligo, enter the ID of the variable set in Paligo. Paligo will then match the imported content to the existing variable set and will not create a duplicate. To find a variable set ID, see Find a Variable Set ID.
However, you can only match one variable set, so if there are multiple in the import, the others will still be duplicated.
-
-
-
Select OK to upload your import zip file.
Paligo will import the content and build a structure with a publication folder and a topics folder. Inside the publication folder there is a publication that links to the created topics. Inside the topics folder there will be subfolders for each article and section, even for unmapped articles and sections.
Note
Depending on how much big the .zip file is, the import might take anywhere from 10 seconds to several minutes.
During content import, if using the setting Match with existing variable set, a variable set ID must be entered to avoid duplicated variable sets. However, you can only match one variable set, so if there are multiple in the import, the others will still be duplicated.
|
Paligo will collect multiple variable sets into one. After the import, you can separate them into multiple variable sets again if required.
Tip
It is possible to configure the import to make translatable variables (the default is plain text variables). Contact support to get the parameter variable.type set to "translation". To learn more about variable sets in Paligo, see Variables.
-
Select Variable sets in the Content Manager.
-
Select the variable set that you want to find the ID for.
-
Look at the URL in the browser's address bar. The ID is immediately after "edit/".
There may be times where you want to get your content out of Paligo. For example, if you want to:
-
Make your own backups that you can import back into Paligo at a later date, if necessary.
For making backups, export your content in the Export Paligo Export File (PEF).
-
Migrate your Paligo content to another system or export it so that it can be converted into DITA or some other XML. For migrating your content out of Paligo,Publish as DocBook XML.
Note
To manipulate the XML outside of Paligo, you can either export to PEF or publish as DocBook 5.1. In most cases, we recommend that you publish as DocBook 5.1 as this is an open standard. PEF is more complex as it contains more information.
Do not manipulate XML outside of Paligo and then import it back into Paligo. This can result in duplicate content. If you need to manipulate XML that you will continue to use in Paligo, use the Oxygen plugin. Open the topics in the Content Manager widget from there.
You can make a backup of your content by exporting it to Paligo Export File (PEF). You can then import the content back into Paligo from your backup file at a later date.
The Paligo Export File (PEF) has DocBook 5.1 elements and metadata and other information about text fragments and variables.
To export to PEF format:
-
Select the Dotted menu (...) for the topic or publication in Content Manager.
-
Select Export content.
Paligo generates an export file in the Paligo Export File format. It downloads in the browser automatically.
-
Store the download in a place where you can easily retrieve it later, for example, on a shared drive.
Note
You can use the Import content option to Import Paligo Export File (PEF) backups into Paligo.
You can publish content to the DocBook 5.1 XML format. This is useful if you want to use your Paligo content in other systems or want to convert it into another type of XML, such as DITA.
When you publish to XML, Paligo produces a standard DocBook 5.1 XML output. You can use it as it is or you could get XSLT specialists to convert it into a different type of XML. The DocBook 5.1 output does not contain any metadata or information about text fragments and variables.
-
Select the Dotted menu (...) for the topic or publication in Content Manager.
-
Select Publish.
Paligo displays the Publish document dialog.
-
Select the XML format in the Publish dialog.
-
Select Publish document.
Paligo will generate the XML output and it will download as a zip file in the browser. You can use an XML editor or similar application to open the file.