You might can imagine that publishing a documentation for every new development, consisting of screenshots, notes and descriptions to this documentation (as well as the translation to English/German) can be a time-consuming task. The requirement to provide the documentation in an additional file format increases the effort enormously, since 2 files have to maintained.
Fortunately, we got a solution for this:
In this blog post we describe how we extended our DOCS (DOCFX) with an PDF file export. The PDF files are automatically created and uploaded to a centralized storage by the pipeline. The PDF files consist of the documentation that you have written in your markdown files in your DOCS repo.
This blog describes the following:
For the following description you need to download and install Git, VS Code, Chocolatey and DOCFX.
Download & Install wkhtmltopdf
First of all, we need to download and install wkhtmltopdf. wkhtmltopdf will later create the PDF files for us.
To download and install wkhtmltopdf, open your VS Code and type the following command in the terminal:
choco install wkhtmltopdf --force -yExport PDF Default Template
Second thing to do is to export the default template for the PDF files. This step is not necessarily needed but in the future it can be helpful, if you want to beautify the generated PDF files (according to your Corporate Design).
Type the following code line in your Terminal in VS Code and press ENTER to export the default PDF template:
docfx template export pdf.default.The default template is exported to a new folder in your repo.
Copy the folder to your preferred templates folder.
Please note that changes made in the default template (which is stored under …\templates\default) will not be applied to your PDF file. You have to copy the default template and specify the new template file in the docfx_pdf.json file (see below – highlighted).
{ "pdf": { "name": "BEYONDCloudConnector_de-DE", "noStdin": true, "content": [ { … (some parts are missing ;)) }, "dest": "../../_site/pdf/", "template": ["default","../../templates/pdf"] } }
In this way the default template is chosen first and "overwritten" by the exported template (stored in the folder "pdf"). All generated PDF files are later uploaded to the folder "pdf" on our website ---> see here: Downloads | DOCS by BEYONDIT (beyond365.de)
Create cover (title) page
Every PDF needs a proper cover page... otherwise your PDF files will start with a TOC (table of Content) and that would be pretty "ugly".
Add a cover file to the folder in which your markdown documentation is stored.
Add PDF Creation Task to Azure Pipeline
Last thing to do is to implement the automatic PDF file generation as a task to the Azure pipeline:
- task: DocFxTask@0 displayName: 'PDF de-DE Cloudconnector' inputs: solution: de-DE/cloudconnector/docfx_pdf.json
We are currently generating 8 PDF files automatically (4 product documentation in German and English). We are publishing the most recent documentation online and simulteanously as a PDF file under: Downloads | DOCS by BEYONDIT (beyond365.de) If you have any question, feel free to ask or write a PM to Jannic.