Administrators can import product documentation into the Knowledge Base from one ZIP file of Markdown documents and images. Importing the same ZIP again later updates the articles.
Where to find it: Content → Knowledge Base, button Import documents (administrators only).
Before you start
- Check the PHP upload limits of your server.
upload_max_filesizeandpost_max_sizemust be larger than the ZIP file. Setup → System → Tools, panel Overview, shows both values. - Plan your category paths: a product and its sections, for example
Ticketix/Getting Started,Ticketix/FeaturesandTicketix/FAQ.
What goes into the ZIP
The examples on this page use the structure of this documentation, which is imported the same way:
categories.json
articles/
ticketix-introduction.md
ticketix-install.md
images/
ticketix-ai-connections-screenshot.webp
categories.json(optional) lists the categories..mdfiles are the articles. They can be in any folder; files whose name starts with_andREADME.mdfiles are skipped.- Images can be in any folder. Each article refers to them with a path relative to its own
.mdfile.
If you zip a folder and everything ends up inside that one folder, Ticketix reads the files below it.
categories.json
A list of categories. path is required; the other fields are optional.
[
{"path": "Ticketix", "slug": "ticketix", "description": "Documentation for Ticketix.", "order": 100},
{"path": "Ticketix/Getting Started", "slug": "ticketix-getting-started", "description": "Install and set up Ticketix.", "order": 10}
]
pathis a product and its section, separated by/. Missing parent categories are created.slug,descriptionandorderapply to the last part of the path. Lowerordervalues come first.
Article front matter
Each .md file starts with front matter between two --- lines, followed by the Markdown body:
---
title: Install Ticketix
slug: ticketix-install
category: Ticketix/Getting Started
order: 30
excerpt: Upload the installation package and run the setup.
tags: install, setup
status: published
visibility: public
---
The body of the article starts here.
| Field | Required | Meaning |
|---|---|---|
| title | Yes | The article title |
| category | Yes | The category path, for example Ticketix/Getting Started; created if it does not exist |
| slug | No | The address of the article; taken from the file name when empty |
| order | No | The order inside the category |
| excerpt | No | A plain-text summary |
| tags | No | Comma-separated tags |
| status | No | published (default) or draft |
| visibility | No | public (default) or internal |
| lang | No | The language of the article, for example en, tr or de (see "Import translations" below) |
Markdown you can use
- Headings with
#. The article title is the page heading, so#and##both become section headings. - Paragraphs,
**bold**,*italic*and inline code. - Code blocks between three backticks.
- One-level bullet lists and numbered lists.
- Tables with
|columns. - Notes with
>at the start of the line. - Horizontal rules.
- Links. Link to another article with
kb:and its slug, for example[Write and publish Knowledge Base articles](kb:ticketix-knowledge-base). - Images with a path relative to the
.mdfile, for example.
Images must be PNG, JPEG, GIF or WebP and up to 5 MB each. Only images stored by Ticketix are shown in articles, so include every image in the ZIP. The same image is stored once, even if several articles use it.
Run the import
- Open Content → Knowledge Base and click Import documents.
- Check the Default language: the language of files that name none (English unless you choose another). Drop the ZIP file into the window, or choose it. Nothing changes yet.
- Ticketix checks the ZIP and shows what would happen: the number of New, Updated and Unchanged articles, Categories and Images, the same counts for each language, the articles that Will be created or updated, and the files that cannot be imported with the reason, for example a missing image or a missing
title. - Click Import … changes to write them, or Cancel.
- Read the result, for example "Import finished: 19 created, 0 updated, 0 unchanged, 4 categories changed, 20 new images."
An error in one file does not stop the others. Fix the file and import the ZIP again. If you wait too long after the check, Ticketix asks you to choose the file again.
Update documentation
Import the new version of the ZIP. Articles are matched by slug and language:
- A new slug creates a new article.
- An existing slug updates the article of the same language. The previous text stays in its revision history, with the change note "Imported from" and the file name.
- An article whose content did not change is counted as unchanged.
Nothing is deleted by an import. To remove an article, archive it in the article list or on its page.
Import translations
A translation has the same slug as its English original and another language. Import translations with a ZIP of their own, after the English documentation, for example:
de_DE/
categories.json
articles/
ticketix-install.md
images/
ticketix-ai-connections-screenshot.webp
- The language of a file is its
lang:line, for examplelang: de; otherwise its language folder at the top of the ZIP (tr/,tr_TR/andde_DE/givetrandde); otherwise the Default language of the import. Any language other than English, Arabic, Turkish, Japanese and German makes that file an error. - A translation takes the category and order of its English original; the
categoryandorderlines of the file are not used. A translation without avisibilityline is staff-only when its original is. The English article does not change. - A translation without an English original is imported as an article of its own, and the check lists it as a warning.
- A
categories.jsonin a language folder, or at the top of a ZIP whose articles are all in one language other than English, finds each category by its Englishpathand writes only that language's name (title, optional) anddescription. The English name, order and parent stay as they are. - Include the images the translated articles use. An image that is already stored, for example from the English documentation, is not stored again.
A translated categories.json entry:
[
{"path": "Ticketix/Getting Started", "slug": "ticketix-getting-started", "title": "Erste Schritte", "description": "Ticketix installieren und einrichten."}
]
See Languages and translated content for what visitors see.
Limits
| Limit | Value |
|---|---|
| Files in the ZIP | Up to 2,000 |
| Total size after extraction | Up to 200 MB |
| Image size | Up to 5 MB per image |
| Image types | PNG, JPEG, GIF and WebP |
For safety, Ticketix refuses a ZIP that contains absolute paths or paths with ...