generate Markdown instead of HTML

[alexanderbaumann-toast]

Hello! We'd like to host the grpc sabledocs in github but the HTML doesn't render.

Is there a way to generate Markdown instead of HTML?

[markvincze]

Hi @alexanderbaumann-toast,

Thanks for the patience on this one! Currently there is no built-in way to achieve this. And even though you can completely rewrite the rendering template, the current logic heavily assumes that we're generating HTML:

• The filenames of the template files need to be index.html, package.html and search.html, that's what the tool look for.
• Some content is only available in the templates in its HTML form, for example the main_page_content field already contains generated HTML. These issues make it difficult to generate Markdown today.

I tried a very crude PoC, and to some extent this might be already possible. I tried creating a new markdown-template folder, put an index.html, package.html and search.html file in it, where package.html and search.html are empty, and added this to index.html:

# Generated gRPC docs

## Packages

This is the list of packages:

{% for p in non_hidden_packages %}
### {{ p.name }}
  {% if p.description %}
    {{ p.description }}
  {% endif %}
{% endfor %}

And added this to the sabledocs.toml:

template-path = "markdown-template"

Then the generated index.html file was like this:

# Generated gRPC docs

## Packages

This is the list of packages:

### google.datastore.v1

### google.pubsub.v1

So with a custom template, this is technically already possible, but it's a quite hacky solution. It'd be nice to have proper support for this scenario, but I don't have any concrete plans for it at the moment.

[alexanderbaumann-toast]

thank you for the response and trying out a POC, I also found a python converted from HTML to MD but it's also not perfect :]