Skip to main content

Use the Import Wizard

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.

Expanded import wizard dialog. It has a field that shows the type of import. Below that, a field for selecting a file, a general options tab and a custom options tab. There is a note advising you that you must upload a zip file containing all documents and images. Another note advises you that there is a file limit of 1GB and the file can only contain one root file.

Tip

The necessary preparations before an import differs between the import types, see Import Types.

To import content to Paligo:

  1. 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.html  for 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.

  2. Select the Dotted menu (...) for the documents folder in the Content Manager. Document_folder_small.png

    Documents_Folder.jpg

  3. Select Create folder. Create_Folder.jpg

  4. Enter a folder name and confirm it with the checkmark. Checkmark_small.png

  5. Select the Dotted menu (...) for the new folder in the Content Manager. Document_folder_small.png

  6. Select Import content. Import_Content.jpg

    Close up of the options menu. The Import content option is highlighted.

  7. Select the Import type from the menu.

    Import content dialog. It has a dropdown for selecting the type of import, a reset button, close button, and OK button.

  8. Select OK.

  9. Select the zip file to be uploaded. New_Layout.jpg

    Expanded import wizard dialog. It has a field that shows the type of import. Below that, a field for selecting a file, a general options tab and a custom options tab. There is a note advising you that you must upload a zip file containing all documents and images. Another note advises you that there is a file limit of 1GB and the file can only contain one root file.

  10. Use the General options tab to set your preferences for the import:

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

    • Import missing images

      When enabled, placeholders for missing images will be added to your Media folder. This is the default setting. Disable this option to disregard missing images.

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

      Swagger_OpenAPI_General_Options.jpg

      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.

      Swagger_OpenAPI_General_Options.jpg
      Programming language tabs shown at top of the API layout, above the code samples.

      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.

      code-snippet-languages-selection.jpg

  11. Use the Custom options tab to set your preferences for the titles, numbering, folder levels, and variables:

    Custom_Options_Tab_small.jpg

    • 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. Disable it if you don't want numbering.

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

      import-folders-set-to-1.jpg
      import-folders-set-to-3.jpg

      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.

      1. The first time you import the content, leave this field blank. Paligo will create a variable set for your content.

      2. If the content has 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.

        Match_Existing_Variable_Set_Option_small.jpg

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