gopages: output markdown format (via custom template?)

[corani]

In my repo I'm using MkDocs to generate a gh-pages site based on the documentation I have in Markdown format. I would like to integrate the godocs within that documentation. Would it be possible to support a custom template for the index files so instead of generating HTML I could generate Markdown instead?

I could probably get MkDocs to include the HTML files, but supporting Markdown would ensure the theme and formatting stays consistent with the rest of the documentation.

[JohnStarich]

Thanks @corani for opening. Are you proposing a single README-like Markdown file at the root, similar to pkg.go.dev? Or more like several markdown files throughout?

If I remember right, the Go doc recommendations say to use # Headings, - Bullet points, and [links] in their own format. In your case, they may be package doc comments. You can see their recommendations here: https://go.dev/doc/comment

[corani]

I mean: currently gopages is generating HTML files (one index.html per package, AFAICS). Instead I'd like to generate markdown files (ideally via a customizable template). While MkDocs can import the HTML files, they end up looking pretty bad and are not fully integrated in the navigation.

[corani]

I guess some way to make it possible to override these: https://github.com/JohnStarich/go/blob/master/gopages/internal/generate/template.go#L98

So that the user could provide their own templates.