This repository contains the code necessary to build the Zimbra User Guide.
This guide is for the end user.
Any images to be included in the documentation must have their source files stored in the images folder, with the following guidelines:
-
Assign a meaningful name: The name of an image should indicate what the content of the image is.
-
Do not replace images: Once an image source file has been merged to
developormasterbranches of the repository, the image is considered immutable. If an update or new version of an image is required, then it should be added as a new image with a version number in its name, so it is clear for translators that images have changed. For example,system-overview.jpgcould be updated withsystem-overview-v2.jpg, with corresponding changes to the file(s) that include the image so they include the new version. -
Images must render in html & pdf output: The
asciidoctor-pdftool should produce apdffile with your image intact. If an image does not render, your PR will be rejected. -
Take care with SVG fonts: If you’re using fonts in your SVG, and you want those fonts to be preserved, those fonts must be defined in the Asciidoctor PDF theme file.
-
Use "pure" SVGs: The SVG renderrer used by
asciidoctor-pdfonly supports "pure" SVGs, not the SVG/HTML/CSS hybrid that are sometimes targeted for web viewing. If your image editor supports export of SVG files without the additional info, use that. Test your images - a hybrid SVG will render as a black rectangle inpdf.
The Zimbra User Guide is written using AsciiDoc. Specifically, it is intended to be processed with Asciidoctor.
As a prerequisite to building the documentation, you will need to have already installed and configured Asciidoctor. Check the Installation Quick Start in the Asciidoctor User Manual for information on how to get started.
Once you have Asciidoctor installed and working, you can build the documentation into HTML files like so:
asciidoctor -a z9 -b html5 -D ~/temp/9 -o userguide-9.html user-guide.adocThe -a z9 builds the document of "Zimbra Collaboration". If you want to build the document for "Zimbra Cloud", plase specify -a zcloud.
PDF output can be generated as well:
asciidoctor-pdf -a allow-uri-read -D ~/temp/9 -o userguide-9.pdf user-guide.adocThis assumes you have a "temp" directory to receive the asciidoctor output, and are generating output for version 9… adjust according to your situation.
Each section of the document is contained in its own file.
You may use the user-guide.adoc file to generate the entire document.
To accompany the HTML output, the images/ folder must also be copied to the output destination:
cp -r ./images ~/temp/9/imagesWhen publishing the output (gh-pages branch) the "latest" link needs to be updated to point at the new version:
ln -nsf 9 latestFinally, the index.html' file in the root folder needs to be updated to include appropriate links for the new version’s documents.
Use your favorite text editor to complete this task before committing and pushing the updated `gh-pages branch to the repo.
|
Note
|
The Best Practice for managing translations would be to replace translatable strings in the English adoc files with localized strings from language-specific po files.
Until that is in place, translated adoc source and images are stored in locale-specific folders.
|
The source repo structure is shown below, and has the following characteristics:
-
The top level folder,
userguide, contains the US English (en_us) documentation source, which is informally designated as the "Master" documentation. This is where all primary information is authored and updated. -
The Master
settings.adocfile contains version information for the release, including all translations. There should be no locale-specificsettings.adocfiles. -
Each locale has its own folder under the "Master", named using the ISO-639 Language Code + ISO-3166 Country Code to name it. For example, the Japanese translation appears under
ja_jp. -
There is a Master
imagesfolder to be used by all locales, except in the case of translated images. -
Each locale may have its own
imagesfolder, named using the Language Code + Country Code just like the source folder. Images take up a lot of space, so translations must not copy all the ones in the Masterimagesfolder, rather they should be used as-is where feasible. -
If any images require translation for a locale, then the translated image should be added to the locale’s images folder. Where translated images are to be embedded, the path to the image will need to explicitly indicate the locale, e.g.,
image::ja_jp/images/<image-name.jpg>. -
The value for
imagesdirset bysettings.adocshould be left as-is, pointing at the Masterimagesfolder.en_us Master Translations +----+ +--------+ | | | | userguide | | | +---+---------+ | | +----+ | +--------+ | | | | +---+ images | | | | +----+ | +------+------+ +--------+ | | | | | | +--------------+ ja_jp | | | | | +-------------+ | +----+ +---- settings.adoc +--------+ | | | | +-------------------------+ ja_jp | | | | | +---+---------+ | | | en_us sources | ja_jp sources | | +--+- user-guide.adoc +--+- user-guide.adoc +- ... +- ...
The documentation output is "published" by being pushed to the gh-pages branch, which is automatically hosted as a public website by GitHub.io.
Each published release-version of the Zimbra User Guide appears in its own release folder.
Translations of documentation are published under the release-version folders, in a structure that is similar to the source organization. For example, consider two versions of the Zimbra User Guide with Japanese translations:
+----+
+--------+ |
| |
| / |
| |
+--+----------+
| en_us Master Translations
+--+- index.html +----+
| +- style.css +--------+ |
| | |
+--------------------+ 8.8.12 |
| | |
| +---+---------+
| |
| | +----+
| | +--------+ |
| | | |
| +---+ images |
| | | | +----+
| | +-----+-------+ +--------+ |
| | | | |
| | +---------------+ ja_jp |
| | | |
| | +-------------+
| |
| | +----+
| | +--------+ |
| | | |
| +-------------------------+ ja_jp |
| | | |
| | +-------------+
| | |
| | en_us docs | ja_jp docs
| | |
| +--+- userguide-8.8.12.html +--+- userguide-8.8.12-ja_jp.html
| +- userguide-8.8.12.pdf +- userguide-8.8.12-ja_jp.pdf
|
| +----+
| +--------+ |
| | |
+--------------------+ 8.8.15 |
| |
+---+---------+
|
| +----+
| +--------+ |
| | |
+---+ images |
| | | +----+
| +-----+-------+ +--------+ |
| | | |
| +---------------+ ja_jp |
| | |
| +-------------+
|
| +----+
| +--------+ |
| | |
+-------------------------+ ja_jp |
| | |
| +-------------+
| |
| en_us docs | ja_jp docs
| |
+--+- userguide-8.8.15.html +--+- userguide-8.8.15-ja_jp.html
+- userguide-8.8.15.pdf +- userguide-8.8.15-ja_jp.pdf
This structure ensures that the relative path to images is the same in both source and published folders, yet the published versions for each release are collected together.
Here is an example of building the Japanese documentation:
asciidoctor -b html5 -D ~/temp/9/ja_jp -o userguide-9-ja_jp.html ja_jp/userguide.adocPDF output can be generated as well:
asciidoctor-pdf -a allow-uri-read -D ~/temp/9/ja_jp -o userguide-9-ja_jp.pdf userguide.adoc|
Note
|
The asciidoctor-pdf tool does not support all languages yet, so the PDF output is optional.
|
The localized images/ folder must also be copied to the output destination:
cp -r ./images/ja_jp ~/temp/9/images/ja_jpVisit www.zimbra.com to join the community and to be a part of building the best open source messaging solution. We appreciate your feedback and suggestions.
Join the Zimbra Forums, to participate and learn more about Zimbra.
For additional product information check the Zimbra Wiki.
© 2016-2026 by Synacor, Inc.
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License unless another license agreement between you and Synacor, Inc. provides otherwise. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
Synacor, Inc., 2026
40 La Riviere Drive, Suite 300
Buffalo, New York 14202