Ability to generate single html file

[bahusoid]

Operation System: Windows DocFX Version Used: 2.44

I want to merge all my specification markdown files to single file html. Is it not supported?

I tried to use file inclusion like:

[!include[file1.md](file1.md)] 
[!include[file2.md](file2.md)] 

But after generation all links are broken in html (link like file1.md#title in file2.md is still converted as file1.html#title instead of "#title").

Anyway it would be useful to have built-in option for single file generation.

[superyyrrzz]

Related to #2297, while this issue need extra merge feature.

Bookmark seems to be a feature request.

• If file1.html is in output, it makes sense to keep file1.html#title.
• If file1.html is not in output, it would be smarter to use #title if included in current article.

[bahusoid]

I was hoping that some kind of merging is already implemented for pdf along with link adjusting. But it seems not to be the case.

If file1.html is in output, it makes sense to keep file1.html#title.

That depends on how this feature is going to be implemented. Ideally I want docfx to be able to build 3 kinds of packages at once: pdf (supported), single file html (missing feature) and multi-file html site (supported).

[superyyrrzz]

That depends on how this feature is going to be implemented. Ideally I want docfx to be able to build 3 kinds of packages at once: pdf (supported), single file html (missing feature) and multi-file html site (supported).

Now generating HTML and PDF at once is supported: you can run docfx against a docfx.json with both build section and pdf section.

[bahusoid]

Yeah I know.. I meant that single html generation should be implemented in similair way. So single html and multi-html can be generated in single step.

[adamgit]

docFX's PDF generation is fundamentally broken and unusable (the library it depends on was killed almost 3 years ago, and core bugfixes submitted as much as 4 years ago were never included into the builds before the author killed it off).

So. We are left with this: docFX clearly is capable of merging everything - it's how it does the PDF generation (wkhtmltopdf requires a single HTML file, so we know docFX is doing this). Does anyone know an (undocumented) way of getting docFX to simply output that file?

Doing that would instantly allow everyone to sidestep the large number of showstopper bugs in docFX's PDF integration.

[paulushub]

docFX's PDF generation is fundamentally broken and unusable

What are the exact issues you are facing now?

wkhtmltopdf requires a single HTML file, so we know docFX is doing this

I think the merging is handled by iTextSharp using PdfStamper.

Does anyone know an (undocumented) way of getting docFX to simply output that file?

If you set keepRawFiles to true, you will see the HTML files, there is no single file.

Doing that would instantly allow everyone to sidestep the large number of showstopper bugs in docFX's PDF integration.

Which bugs are you experiencing, please report them.

[adamgit]

All the bugs I'm encountering were reported multiple years ago. No-one is maintaining wkhtmltopdf (c.f. their github project and the pinned issue at top of the page), and it has been officially dead for a number of years.

The docFX-side issues (sometimes directly due to wkhtmltopdf bugs, sometimes docFX specific) have also been reported multiple times, most of them have live github issues dating back years, the rest are widely documented on stackoverflow (and across the web) with multiple people every year raising the same issues and getting the same responses: broken in docfx, nothing you can do about it, it's not maintained. There is no point re-reporting bugs that are already well known while docfX itself is not being actively developed.

I don't expect docFX to start being developed again, but people following these issues sometimes have critical info that never made it to docFX's own documentation (e.g. the PDF docs on main website for docFX are out of date, with missing pieces only existing inside responses to some of these GH issues).

Thanks for the tip on PdfStamper - gives me something to explore!

[paulushub]

There is no point re-reporting bugs that are already well known while docfX itself is not being actively developed.

Not really a true picture in my view. DocFX 2 is no longer used internally and now in maintenance mode here. For DocFX 3, it seems to be a unique product in that it is developed internally for docs.microsoft.com uses and parts opened to the public. It seems that part of cleaning up docs.microsoft.com specific features is a never ending task since the project is internally evolving, and the desire to make it cross-platform is also a factor here.

All the bugs I'm encountering were reported multiple years ago.

Many wkhtmltopdf issues are reported (per the project site), I was hoping you could report on your specific needs as least for reference.

[yufeih]

Single HTML output is also a candidate approach to replace the current wkhtmltopdf based PDF solution. #4250