Unable to insert cover page into pdf

[Chris-R-R]

Operating System: Windows

DocFX Version Used: 2.58.9.0

Template used: (default or statictoc or contain custom template)

Steps to Reproduce:

1. Added file "cover.md" in same folder as toc.yml
2. Referenced cover.md file in pdf content section of docfx.json
3. Generated documentation ("docfx metadata", "docfx"

Expected Behavior: I expected the cover page to appear at the beginning of the pdf

Actual Behavior: No cover page in the pdf. However, in the _site\articles folder, a cover.html page has been generated. A warning is generated by docfx - "[22-02-08 07:30:30.094]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]There is no template processing document type(s): cover"

I looked at #2004 and #4342 to try and understand how to do this so it's possible I am misunderstanding something. The documentation could definitely be clearer about this.

[DmitriyYukhanov]

I can confirm this with DocFX 2.59.0.0 and wkhtmltopdf 0.12.6 on Windows 10.

The interesting thing, cover.html generates just fine, it just doesn't get fed into the wkhtmltopdf using cover object.

[MiTschMR]

Any news on this issue? It is affecting me as well, same version as Dmitriy.

[paulushub]

@DmitriyYukhanov @MiTschMR It works for me. There are two ways to configure this.

1. If you have a cover.html, then
   • place it in the same directory as your docfx.json file and
   • Include that in the command-line to the wkhtmltopdf program

   "wkhtmltopdf": {
     "additionalArguments": "--dpi 300 --footer-center [page] --margin-top 25 --margin-bottom 25 --margin-left 25 --margin-right 25 cover cover.html"
   },	
   

2. If you have a cover.md, then
   • place it in the pdf folder (as the TOC of the pdf)
   • modify the content section to include markdown files
   • make sure the cover.md file includes the documentType: cover, as shown below.

Sample cover.md

---
documentType: cover
---
# Cover Page Title

# Test Cover Page

This is the cover page of this test documentation.

Sample docfx.json

{
  "metadata": [
    {
      "src": [
        { 
			"src":"../",
			"files":"*.csproj"
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
      "properties":{
			"TargetFramework":"net6.0"
		}
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
	"xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "templates/default"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  },
"pdf": {
    "content": [
        {
            "files": [ 
			  "pdf/*.md",		
			  "pdf/toc.yml"			
		  ]
        },
        {
            "files": [
                "api/**.yml",
                "api/index.md"
            ],
            "exclude": [
                "**/toc.yml",
                "**/toc.md"
            ]
        },
        {
            "files": [
                "articles/**.md",
                "articles/**/toc.yml",
                "toc.yml",
                "*.md"
            ],
            "exclude": [
                "**/bin/**",
                "**/obj/**",
                "PDF/**",
                "**/toc.yml",
                "**/toc.md"
            ]
        }
    ],
    "resource": [
        {
            "files": [ "images/**" ],
            "exclude": [
                "**/bin/**",
                "**/obj/**",
                "PDF/**"
            ]
        }
    ],
    "dest": "_pdf",
     "keepRawFiles": true,
    "wkhtmltopdf": {
      "additionalArguments": "--dpi 300 --footer-center [page] --margin-top 25 --margin-bottom 25 --margin-left 25 --margin-right 25"
    },		
  }  
}

DocFX Version Used: 2.59.3

[MiTschMR]

That works, thanks a lot!