Skip to content

Latest commit

 

History

History
157 lines (92 loc) · 6.49 KB

README.md

File metadata and controls

157 lines (92 loc) · 6.49 KB

Markdown to PDF converter

This is a Azure DevOps pipeline to publish a PDF artifact by converting Markdown files using a predefined template.

Get started

To use the pipeline, several prerequisite steps are required:

  1. If needed, create a repo.

  2. If needed, add markdown documentation to the repo. It is recommended to keep the markdown files in a subfolder of a "docs" folder, for example "docs/hld".

  3. Add a "document.order" file in the markdown folder. It is recommended to only keep one order in each markdown folder.

  4. Add markdown file names to "document.order", one file name for each line.

    Ensure that the file names are in the correct order. This is how they will appear in the PDF file.

    Note that lines that start with the comment sign # will be ignored.

  5. Add the markdown2pdf.yml to a repo folder with a name that represent what it converts, e.g. ".pipelines/docs.dns.design.yml".

  6. Customize the variable values in the pipeline file and commit the changes.

  7. Go to the Azure DevOps Pipelines page. Then choose the action to create a New pipeline.

  8. Select Azure Repos Git as the location of the source code.

  9. When the list of repositories appears, select the repository.

  10. Select Existing Azure Pipelines YAML file and choose the YAML file, e.g. "/.pipelines/docs.dns.design.yml".

  11. Save the pipeline without running it.

  12. Configure branch policies for the default/main branch.

  13. Add a build validation branch policy.

Pipeline

The pipeline converts markdown to PDF using a script and a LaTeX template.

Template sections

The template has the following sections:

  1. A Title page with a cover logo and the document title and subtitle.

  2. A Version history page. The content of this page is generated based on the following:

    1. If a HistoryFile exist; use the content of that file.
    2. Or, if SkipGitCommitHistory is set to true or a commit history don't exist; use the value of MainAuthor and FirstChangeDescription.
    3. Or, use git commit history. Limit the number of items to the value of GitLogLimit.

  3. A Table of Content page.

  4. Content pages with the converted markdown files. This content is generated based on the following:

    1. Merge the markdown files listed in the "OrderFile" to one markdown file.
    2. Replace markdown links that have a relative path with a absolute path.
    3. If a ReplaceFile exist; update the markdown file and replace each string that match the key from ReplaceFile, with the matching value.
    4. Build metadata for the "pandoc" converter.
    5. Convert the markdown using "pandoc" and save it as an artifact to the job.

  5. Page header on all pages, except for the Title page:

    • Left side: logo
    • Center: Project and Author(s)
    • Right side: Current date.

  6. Page footer on all pages, except for the Title page.

    • Center: page number and total number of pages.

Markdown tips

The markdown can include admonition blocks for text that need special attention.

The following blocks are supported: warning, important, note, caution, tip

Example:

# A title

This is some regular text.

::: tip
This text is in a tip admonition block.
:::

Issues

The following are known issues:

  • Relative paths should start with ./ to ensure it can be replaced with absolute path before converting it to PDF.
  • Markdown table columns can overlap in the PDF if the table is to wide, making text unreadable. To work around this:
    • limit the text in the table. Typically it should be less than 80 characters wide.
    • split the table up.
    • use an ordered or unordered list.
  • The template is designed for a standing A4 layout. It has no option to flip page orientation for one or several pages in a document.
  • Titles are not automatically numbered. Titles can be manually numbered and maintained in the markdown document. To avoid having to manually update all titles, it is best to not use numbered titles if possible.

Variables

  • FIRST_CHANGE_DESCRIPTION: The first change description. This value will be used if a HistoryFile is not specified and a git commit comment is not available.

  • FOLDER: The repository folder where the order file exist.

  • GIT_LOG_LIMIT: Maximum entries to get from Git Log for version history.

  • HISTORY_FILE: The name of the history file. This is a file with the version history content. The file must contain the following structure:

    Version|Date|Author|Description

    Example content for a history.txt file:

    1|Oct 26, 2023|Jane Doe|Initial draft 2|Oct 28, 2023|John Doe|Added detailed design

  • MAIN_AUTHOR: The main author of the PDF content. This value will be used if a HistoryFile is not specified and author can't be retrieved from git commits.

  • ORDER_FILE: The name of the .order file. This is a text file with the name of each markdown file, one for each line, in the correct order.

    Example content for a document.order file:

    summary.md details.md faq.md

  • OUT_FILE: The name of the output file. This file will be uploaded to the job artifacts.

  • PROJECT: The project ID or name.

  • REPLACE_FILE: The name of the replace file. This is a JSON file with key and value strings. Each key will be searched for in the markdown files and replaced with the value before conversion to PDF.

  • SKIP_GIT_COMMIT_HISTORY: Skip using git commit history. When set to true, the change history will not be retrieved from the git commit log.

  • SUBTITLE: The document subtitle.

  • TITLE: The document title.

    Example content for a replace.json file:

    {
  "{data center name}": "WE1",
  "{organization name}": "contoso"
}

  • WORKFLOW_VERSION: The version of the markdown2pdf scripts to use. See https://github.com/innofactororg/markdown2pdf/tags.

License

The code and documentation in this project are released under the BSD 3-Clause License.