{"id":20631378,"url":"https://github.com/maxmelcher/azuredevops.wikipdfexport","last_synced_at":"2025-03-08T22:35:26.055Z","repository":{"id":40561243,"uuid":"191395060","full_name":"MaxMelcher/AzureDevOps.WikiPDFExport","owner":"MaxMelcher","description":"Export Azure DevOps Wiki to PDF","archived":false,"fork":false,"pushed_at":"2024-05-10T18:58:44.000Z","size":1295412,"stargazers_count":194,"open_issues_count":13,"forks_count":71,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-17T07:09:55.489Z","etag":null,"topics":["azuredevops","pdf","wiki"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaxMelcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-11T15:01:37.000Z","updated_at":"2024-12-21T15:30:14.000Z","dependencies_parsed_at":"2024-05-10T19:53:29.511Z","dependency_job_id":"8bfb02a2-b021-4deb-9024-678c09e45700","html_url":"https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxMelcher%2FAzureDevOps.WikiPDFExport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxMelcher%2FAzureDevOps.WikiPDFExport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxMelcher%2FAzureDevOps.WikiPDFExport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxMelcher%2FAzureDevOps.WikiPDFExport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxMelcher","download_url":"https://codeload.github.com/MaxMelcher/AzureDevOps.WikiPDFExport/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242619114,"owners_count":20159001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azuredevops","pdf","wiki"],"created_at":"2024-11-16T14:12:07.782Z","updated_at":"2025-03-08T22:35:26.036Z","avatar_url":"https://github.com/MaxMelcher.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 🏎 Quickstart\nThis 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:\n![Clone a wiki](images/CloneWiki.png)\n\nTo clone this wiki, use the following command:\n`git clone https://dev.azure.com/mmelcher/AzureDevOps.WikiPDFExport/_git/AzureDevOps.WikiPDFExport.wiki`\n\nThe result should look like this: \n![Cloned wiki repository](images/Clone.png)\n \nOnce you have cloned the wiki, you must download the Azure DevOps WikiPDFExport tool.\n**[azuredevops-export-wiki.exe](https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport/releases)** (~30MB)\n\nYou can drop it right into the cloned folder and execute it there. \nLaunched 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](./doc/export.pdf).\n\nIf you need more control over the output, please see the Configuration Options below or by launching the tool with --help parameter.\n\n## 💪 Features\n\nThe tool currently supports the following:\n* Export all wiki pages (and sub pages) in the correct order including styles and formatting.\n* Includes pictures (remote and relative urls)\n* Table of Contents\n* If you link to other wiki pages, the link in the PDF will work, too. \n* Everything self-contained. Download the .exe file, run it, done.\n* It is fast. A PDF with 160 pages is created in less than a second.\n* Tool can be used as part of a build, see [BuildTask](doc/Build-Task.md)\n* Supports emoticons :) ⚠ ℹ\n* Mermaid supported \n* Workitems can be referenced and will be included in the pdf as link with the current status, e.g. #7.\n* Math/Latex formulas are rendered\n\n## 🛰 Requirements\n\nThe tool is developed as .NET 6 application, therefore you need to have the runtime installed. \nDownload is available [here](https://dotnet.microsoft.com/download).\nIt requires a x64 **windows** or **linux** runtime.\n\n## 🔽 Download\n\nThe download is available [here](https://github.com/MaxMelcher/AzureDevOps.WikiPDFExport/releases)\n\n## ⚙ Configuration Options\n### --attachments-path\nPath to the .attachments folder.  If not provided, the .attachments is assumed to be located under the folder of the wiki (-p/--path).\n### -b / --breakPage\nFor every wiki page a new page in the PDF will be created\n### --chrome-path\nPath 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.\n### --css \nPath to the stylesheet to overwrite the look of certain components in the PDF. See [styles.css](./doc/styles.css) for examples. To get the html file, use the [--debug flag](#-d----debug) to inspect and style it.\n### -c / --highlight-code \nHighlight code blocks using highligh.js\n### -d / --debug\nDebug mode. Logs tons of stuff and even exports the intermediate html file\n### --disableTelemetry\nDisables the telemetry tracking, see [Telemetry](#-telemetry)\n### --exclude-paths\nSkip pages whose path matches the [regular expression](https://docs.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) patterns.  \nTo 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)\n### --filter\nFilters the pages depending on the page [yaml tags](https://docs.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops#yaml-tags).\n### --footer-template, --header-template,\nHeaders and footers can be added to the document by the --header-* and\n  --footer* template arguments respectfully.  In header and footer string supplied\n the following variables will be substituted. See [PDF options from puppeteer](https://pptr.dev/#?product=Puppeteer\u0026show=api-pagepdfoptions). \n\n   * [pageNumber]       Replaced by the number of the pages currently being printed\n   * [topage]     Replaced by the number of the last page to be printed\n   * [totalPages]       Replaced by the current date in system local format\n\n### --footer-template-path, --header-template-path\nProvide a path to html files that will be added as header and footer. See [example-footer.html](./doc/example-footer.html), [example-header.html](./doc/example-header.html).\n\n### --globaltoc\nTitle for a global table of content for all markdown files. When not specified each markdown creates its own toc if defined\n\n### --globaltocposition\nOrder of TOC within all files (starting from 0). When not specified TOC will be printed on the first page\n\n### --include-unlisted-pages\nBy default only pages listed in `.order` files are considered. Setting this option any Markdown file (`.md`) found will be included as-well.\n\n### --no-frontmatter\nIf you want to remove the [frontmatter / YAML tags](https://docs.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops#yaml-tags) from the PDF. \n\n### --chrome-timeout\nTimeout for Chrome operations in seconds (default 30 seconds).\n\n### --open\nOpens the PDF file after conversion. Great for development, not great in a build task.\n### -o / --output\nThe path to the export file including the filename, e.g. c:\\export.pdf\n### --organization \nAzure Devops organization URL used to convert work item references to work item links. Ex: https://dev.azure.com/MyOrganizationName/\n### -p / --path\nPath to the wiki folder. If not provided, the current folder of the executable is used.  \nIf you only want to convert a subfolder and have images, then you must provide the path to the attachments folder with --attachments-path.\n### --pat\nPersonal access token used to access your Azure Devops Organization. If no token is provided\nand organization and project parameters are provided, it will start a prompt asking you to login.\n### --pathToHeading\nAdd path of the file to the header\n### --printbackground\nEnable print background when using no header/footer template.\n### -s / --single\nPath 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.\n### -v / --verbose\nVerbose mode. Logging will added to the console window\n\n## Running in Docker\n\nTo build the Docker Image run the following commands (replace `\u003cVERSION\u003e`):\n\n~~~powershell\ndotnet publish -r linux-x64 -c Release -p:Version=\u003cVERSION\u003e --no-self-contained  -o output/linux-x64\ndocker build --pull --rm -f \"Dockerfile\" -t azdowiki-pdf-export:latest \".\"\n~~~\n\nLaunch a container:\n\n~~~powershell\ndocker run -it -v ${pwd}:/usr/root/wiki -w /usr/root/wiki azdowiki-pdf-export:latest bash\n~~~\n\nChange the volume mapping (`-v ${pwd}`) to the location of your wiki and then\nrun `azuredevops-export-wiki -p .` to generate your PDF.\n\n## 😲 Limitations\n\nSo far the following limitations are known:\n* If headers are not formatted properly (#Header instead of # Header), they are rendered incorrectly. I might fix that in the future.\n* The tool lacks proper testing because I only have two realistic wikis available. Want to contribute one?\n* Currently, no pdf bookmarks are created (see [chromium issue](https://bugs.chromium.org/p/chromium/issues/detail?id=781797)).  \n* Tags in Azure DevOps must be closed properly - if you leave a strikethrough (`~~`) open, then all the following ~~content will be striked through~~.\n\n## ⚖ License\nSee [license](/License.md)\n\n## 🎯 Telemetry\nThe tool uses Application Insights for basic telemetry:\n- The duration of the export and the count of wiki pages is tracked and submitted to Azure. \n- In the case of an error, the exception is submitted. \n- No wiki data/content is submitted.\n\n## ❓ FAQ\n\n### Some pages are missing? \nPlease check the .order files in your wiki if the pages are listed in there.\n\n### The emoticons are missing in the PDF? \nPlease check if you have page file that are encoded (e.g. Test%20dFiles.md)\n\n### There is an error 'Qt: Could not initialize OLE (error 80010106)'. \nYes, please ignore for now.\n\n### Does it also work for Github? \nYes, 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.\n\n### Does it run on Linux? \nI only tested Ubuntu 18.04 - but there it works. I installed the following packages: \n```\napt-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\n```\n\n## ♥ Thanks\n\nIn this tool uses open source libraries that do the actual work - I just combined them to get the export as PDF:\n1. [CommandLineParser](https://github.com/commandlineparser/commandline) to parse the command line\n1. [MarkDig](https://github.com/lunet-io/markdig/) to parse markdown files to HTML.\n1. [dotnet-warp](https://github.com/Hubert-Rybak/dotnet-warp) to release a self-contained exe file\n1. [puppeteer-sharp](https://github.com/hardkoded/puppeteer-sharp) to convert mermaid markdown to SVG\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmelcher%2Fazuredevops.wikipdfexport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxmelcher%2Fazuredevops.wikipdfexport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxmelcher%2Fazuredevops.wikipdfexport/lists"}