Perl-written MkDocs equivalent to convert trees of Markdown or POD to HTML with index in each file

Question

Current situation

I like the git-push-triggered documentation generation service of ReadTheDocs. It's nicely layouted, can cope with cross-references between documentation files and generates a nice outline for navigation.

I also have no issue with writing my documentation in Markdown generally, in contrary.

I currently have a Perl based project whose current documentation is written in Markdown and readable online either at ReadTheDocs where it is generated with MkDocs which is written in Python, or at GitHub without any useful table of contents. The man page is currently generated from Markdown with Ronn which is written in Ruby.

Goal

I'd like to upload to above mentioned Perl based project to CPAN, the Comprehensive Perl Archive Network. For that I'd like to have a pure Perl based toolchain for generating the documentation (especially HTML and man page), too.

My research so far

One easy way to achieve that seemed to move all documentation to POD (Perl's Plain Old Documentation Format), because both, pod2html as well as pod2man, exist for a long time and because it's Perl's native documentation format.

While there is quite a lot of POD to something converters, there seem to no equivalent to MkDocs. Pod::Tree's pods2html comes close, but misses relevant features like including the outline of all files in each file or configuring an explicit file order instead of alphabetical for the generated index.

I've also already asked the ReadTheDocs guys if they would support rendering from POD in addition to Markdown, too, but they denied the request with Arguments like "CPAN already does that", but CPAN has no VCS push support at all which was one of my main point.

I've also looked at GitHub Pages since GitHub is able to render POD, but GitHub Pages only supports plain HTML or Jekyll which -- according to itself -- supports a myriad of input formats, but not POD. (And Jekyll is written in Ruby, too, so wouldn't be suitable for local documentation generation either.)

There are other projects similar to MkDocs, but none of them would be an improvement for me, so I don't take them into consideration:

• Daux: written in PHP and primarily meant for server-side.
• Beautiful Docs: written in CoffeeScript and hence having way less common and widespread dependencies (CoffeeScript, Node.js and NPM as far as I can see from a first glance) than MkDocs (Python).
• Flatdocs: Renders Markdown inside the web browser, i.e. requires a browser with JavaScript interpreter as well as JavaScript being enabled. IMHO a fat no-go for documentation.

Current requirements and wishlist items

Hard requirements

It needs to be …

• written in Perl;
• Free Software;
• able to convert multiple POD or Markdown files to multiple HTML files where each HTML file includes a complete index of all files.
• The order in the file index included in each file needs to be customizable.

Soft requirements

It should be …

• available on CPAN.

Nice-to-have features

I would be nice, if

• the link texts in the file index included in each file are customizable;
• it is available as hosted service similar to ReadTheDocs.

Answer 1

Have you considered sticking with Markdown for your actual documentation and adding a POD module to pandoc or to Sphinx to generate your POD files.

• written in Perl; No
• Free Software; Yes
• able to convert multiple POD or Markdown files to multiple HTML files where each HTML file includes a complete index of all files. Yes
• The order in the file index included in each file needs to be customizable. - I suspect so.

Answer 2

Since I haven't found anything which fulfils my requirements, I started to write the according tool myself. It's far from production ready and doesn't have a proper name yet, but very basic functionality is already there.