This tool exports an Azure DevOps wiki as PDF. Therefore, you need to git clone the target wiki to a computer. You can get the clone link of the wiki in the top right of the wiki homepage:
To clone this wiki, use the following command:
git clone https://dev.azure.com/mmelcher/AzureDevOps.WikiPDFExport/_git/AzureDevOps.WikiPDFExport.wiki
The result should look like this:
Once you have cloned the wiki, you must download the Azure DevOps WikiPDFExport tool. azuredevops-export-wiki.exe (~30MB)
You can drop it right into the cloned folder and execute it there. Launched without parameters, the tool will detect all wiki files next to it and convert it to a PDF called export.pdf right next to it. Similar to this pdf.
If you need more control over the output, please see the Configuration Options below or by launching the tool with --help parameter.
The tool currently supports the following:
The tool is developed as .NET 6 application, therefore you need to have the runtime installed. Download is available here. It requires a x64 windows or linux runtime.
The download is available here
Path to the .attachments folder. If not provided, the .attachments is assumed to be located under the folder of the wiki (-p/--path).
For every wiki page a new page in the PDF will be created
Path of the chrome or chromium executable. It'll be used if mermaid diagrams support is turned on (-m/--mermaid). If not specified, a headless version will be downloaded.
Path to the stylesheet to overwrite the look of certain components in the PDF. See styles.css for examples. To get the html file, use the --debug flag to inspect and style it.
Highlight code blocks using highligh.js
Debug mode. Logs tons of stuff and even exports the intermediate html file
Disables the telemetry tracking, see Telemetry
Skip pages whose path matches the regular expression patterns.
To exclude any files in the folders "Scrum" and "Release" but not the file "Released-Version.md", use --exclude-paths /Scrum/ /Release/
(paths are internally normalized to forward slashes and the passed values will be surrounded by .*
automatically to enable partial matches)
Filters the pages depending on the page yaml tags.
Headers and footers can be added to the document by the --header- and --footer template arguments respectfully. In header and footer string supplied the following variables will be substituted. See PDF options from puppeteer.
Provide a path to html files that will be added as header and footer. See example-footer.html, example-header.html.
Title for a global table of content for all markdown files. When not specified each markdown creates its own toc if defined
Order of TOC within all files (starting from 0). When not specified TOC will be printed on the first page
By default only pages listed in .order
files are considered. Setting this option any Markdown file (.md
) found will be included as-well.
If you want to remove the frontmatter / YAML tags from the PDF.
Timeout for Chrome operations in seconds (default 30 seconds).
Opens the PDF file after conversion. Great for development, not great in a build task.
The path to the export file including the filename, e.g. c:\export.pdf
Azure Devops organization URL used to convert work item references to work item links. Ex: https://dev.azure.com/MyOrganizationName/
Path to the wiki folder. If not provided, the current folder of the executable is used.
If you only want to convert a subfolder and have images, then you must provide the path to the attachments folder with --attachments-path.
Personal access token used to access your Azure Devops Organization. If no token is provided and organization and project parameters are provided, it will start a prompt asking you to login.
Add path of the file to the header
Enable print background when using no header/footer template.
Path to a single markdown file to convert to PDF. If you want to write your changelog in the wiki, this is your parameter to only convert a single page.
Verbose mode. Logging will added to the console window
To build the Docker Image run the following commands (replace <VERSION>
):
dotnet publish -r linux-x64 -c Release -p:Version=<VERSION> --no-self-contained -o output/linux-x64
docker build --pull --rm -f "Dockerfile" -t azdowiki-pdf-export:latest "."
Launch a container:
docker run -it -v ${pwd}:/usr/root/wiki -w /usr/root/wiki azdowiki-pdf-export:latest bash
Change the volume mapping (-v ${pwd}
) to the location of your wiki and then
run azuredevops-export-wiki -p .
to generate your PDF.
So far the following limitations are known:
~~
) open, then all the following See license
The tool uses Application Insights for basic telemetry:
Please check the .order files in your wiki if the pages are listed in there.
Please check if you have page file that are encoded (e.g. Test%20dFiles.md)
Yes, please ignore for now.
Yes, but there the .order files are missing to determine the sort order of pages. You would need to create them by yourself, but it is possible.
I only tested Ubuntu 18.04 - but there it works. I installed the following packages:
apt-get install -y gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget libgbm-dev ttf-ancient-fonts
In this tool uses open source libraries that do the actual work - I just combined them to get the export as PDF: