Is it possible to obtain generated markdown files of the docstrings from mkapi?

[mcarans]

My organisation is considering using GitBook. It looks like that tool needs markdown input. Is it possible to obtain markdown file output from mkapi that is generated from the docstrings?

[lmuenter]

I have to second this question. For a multi-repo docs service, we also require rendered markdown. Is it possible to obtain the generated markdown?

[daizutabi]

@mcarans @lmuenter I've added a save option in version 4.4.1 that will save the markdown files of API pages to the docs_dir.

Usage:

plugins:
  - mkapi:
      save: true  # Save markdown files

When this option is enabled:

• Markdown files for API pages will be saved to docs_dir
• Files will be saved in the corresponding paths within docs_dir

Note: The saved markdown files contain HTML elements (like <div> tags and Font Awesome icons) that are specific to MkDocs. When these files are used with GitBook or other tools, you may need to modify the HTML elements to match your target documentation system's requirements.

[mcarans]

@daizutabi This is great news! I have tested and it works for me. Would it be possible to make the output directory configurable?

One way could be to have a default of the docs_dir, but add the facility to change it to somewhere else by passing an additional configuration option.

A cleaner way might be changing the existing save option to accept a path instead of a boolean.

[daizutabi]

@mcarans I've enhanced the save option in version 4.4.2 to accept both boolean and string values. Now you can specify a custom directory for saving the markdown files:

plugins:
  - mkapi:
      save: "output/markdown"  # Save to custom directory relative to the current directory

When save is a string, files will be saved to the specified directory (relative to the current directory) instead of docs_dir.

The existing boolean behavior remains unchanged:

plugins:
  - mkapi:
      save: true  # Save to docs_dir (existing behavior)

[mcarans]

@daizutabi That's great! Thanks a lot. You mentioned about the HTML elements and I noticed a small issue that the <span> elements inside a <p> don't look right in a markdown viewer eg.

<p class="mkapi-object mkapi-page-source" id="hdx.utilities.compare" markdown="1">
<span class="mkapi-object-link">

<span class="mkapi-document-toggle" title="Toggle all docs">
<i class="fa-regular fa-square-minus"></i>
</span>
</span><span class="mkapi-object-kind">module</span>
<span class="mkapi-object-name">[hdx.utilities.compare](compare.md#hdx.utilities.compare "hdx.utilities.compare")</span>
</p>

produces this output:

module [hdx.utilities.compare](compare.md#hdx.utilities.compare "hdx.utilities.compare")

The inner <span> on its own:

<span class="mkapi-object-name">[hdx.utilities.compare](compare.md#hdx.utilities.compare "hdx.utilities.compare")</span>

looks ok:
hdx.utilities.compare

Is this something that can be fixed?

[peekxc]

Along a similar note, a basic CLI option to selectively generate the output markdown / html could be useful for other doc generators that don't natively support mkapi e.g. zensical (which could replace mkdocs-material in the next year or so)