# Mkdocs for Docs **URL:** \ **Category:** Get Help\ **Tags:** documentation\ **Created:** [July 15, 2024, 5:09pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283 "2024-07-15T17:09:32Z")\ **Posts on this page:** 19\ **Page:** 1
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 15, 2024, 5:09pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/1 "2024-07-15T17:09:33Z")
I’m looking to see if there are any examples that are publicly available about using mkdocs-material for hosting the collections docs? Mkdocs-material theme provides a lot of capabilities that it would be good to incorporate further. Such as a version admonition. ---
**Author:** ![mariolenz](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/mariolenz/32/108_2.png) [@mariolenz](https://forum.ansible.com/u/mariolenz)\ **Post date:** [July 15, 2024, 5:47pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/2 "2024-07-15T17:47:25Z")
I’m not an expert on the documentation stuff, but maybe someone from [@Docs](https://forum.ansible.com/groups/docs) could help here. ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [July 15, 2024, 8:45pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/3 "2024-07-15T20:45:04Z")
I don’t know of a mkdocs one for collection docs, but there is the following for a sphinx-based docsite for a collection - [Creating a collection docsite - antsibull-docs – Ansible Documentation Build Scripts](https://ansible.readthedocs.io/projects/antsibull-docs/collection-docs/) ---
**Author:** ![oranod](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/oranod/32/1434_2.png) [@oranod](https://forum.ansible.com/u/oranod)\ **Post date:** [July 15, 2024, 9:30pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/4 "2024-07-15T21:30:18Z")
The Ansible mkdocs theme is built on material: [GitHub - ansible/mkdocs-ansible: Ansible MkDocs Theme based on Material](https://github.com/ansible/mkdocs-ansible) Not sure there are any collections docs using it though. ---
**Author:** ![isuftin\_at\_usgs](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/isuftin_at_usgs/32/925_2.png) [@isuftin\_at\_usgs](https://forum.ansible.com/u/isuftin_at_usgs)\ **Post date:** [July 16, 2024, 3:19pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/5 "2024-07-16T15:19:11Z")
So… I’m kind of in the same boat right now. I’m trying to create a sample Ansible collection, currently which only contains a few roles. So I have role documentation done both in markdown as README.md in each role’s directory and also as meta/argument\_specs.yml. antsibull-docs does well in creating the HTML for the roles via ` antsibull-docs sphinx-init --use-current --dest-dir built-docs`. But we also use mkdocs to convert all markdown in the project into an HTML site. The problem I’m about to try and figure out is: - Can I use antsibull-docs to write markdown to then be picked up by mkdocs? (Edit: Probably not - [Allow markdown? · Issue #20 · ansible-community/antsibull-changelog · GitHub](https://github.com/ansible-community/antsibull-changelog/issues/20) ) - Can I use mkdocs to convert rst along with markdown to html, since antsibull-docs also generates rst (Edit: No - [Question: Can the source be RestructuredText (rst)? · Issue #1817 · mkdocs/mkdocs · GitHub](https://github.com/mkdocs/mkdocs/issues/1817#issuecomment-504794792) ) - Can I use a third tool to convert rst over to markdown to feed mkdocs? (Edit: There is now - [python translate script for converting site from sphinx-build to mkdocs-material · squidfunk/mkdocs-material · Discussion #6092 · GitHub](https://github.com/squidfunk/mkdocs-material/discussions/6092) ) - Is there some standard for documenting collections like there is for roles and plugins? The [Official documentation](https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_documenting.html#documenting-collections) only talks about roles and plugins. So without guidance there, I’m left to free-form a README.md at the root of the project. - How to properly merge my overall collection project markdown with the content coming from antsibull-docs to make it look coherent? - How to do all of this within a GitLab tag pipeline 😃 ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [July 16, 2024, 5:48pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/6 "2024-07-16T17:48:13Z")
antsibull-docs right now has no support for generating MarkDown, though that shouldn’t be too hard to implement. The main problem I see with MarkDown is that it has not very good support for tables (see option/return/attribute tables), except by adding HTML blobs for these, and that links to specific parts of other documents are cumbersome. This is something RST is far better at. > [@isuftin\_at\_usgs](#): > > Can I use antsibull-docs to write markdown to then be picked up by mkdocs? (Edit: Probably not - [Allow markdown? · Issue #20 · ansible-community/antsibull-changelog · GitHub](https://github.com/ansible-community/antsibull-changelog/issues/20) ) That issue is for antsibull-changelog, not for antsibull-docs 🙂 There is currently no issue for antsibull-docs for that… (Feel free to create one, the repo is here: [GitHub - ansible-community/antsibull-docs: Tooling for building Ansible documentation](https://github.com/ansible-community/antsibull-docs/)) ---
**Author:** ![isuftin\_at\_usgs](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/isuftin_at_usgs/32/925_2.png) [@isuftin\_at\_usgs](https://forum.ansible.com/u/isuftin_at_usgs)\ **Post date:** [July 16, 2024, 6:02pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/7 "2024-07-16T18:02:48Z")
@felixfontein When you say MD having poor support for tables, what would you say is missing? ---
**Author:** ![isuftin\_at\_usgs](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/isuftin_at_usgs/32/925_2.png) [@isuftin\_at\_usgs](https://forum.ansible.com/u/isuftin_at_usgs)\ **Post date:** [July 16, 2024, 6:04pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/8 "2024-07-16T18:04:29Z")
And actually while I have you here… 😃 …do you know if there’s any sort of standard for argument\_specs.yml-type documentation-as-code for Ansible collections and playbooks? I love that it’s implemented for roles and plugins but it really feels like collections and playbooks are kind of left to the developer’s interpretation. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [July 16, 2024, 7:02pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/9 "2024-07-16T19:02:35Z")
> [@isuftin\_at\_usgs](#): > > @felixfontein When you say MD having poor support for tables, what would you say is missing? You cannot have more than one paragraph inside a table cell, and anything but the most basic formatting is hard. (Compare that to RST list tables, where you can put a lot of stuff inside a table cell. That’s basically what antsibull-docs is using for the Sphinx output. For the ‘simplified RST’ output - suitable for example for GitHub - it uses HTML blobs, since GitHub’s RST renderer didn’t supported list tables. It might do now, since they made big changes to their RST renderer this year…) > [@isuftin\_at\_usgs](#): > > And actually while I have you here… 😃 …do you know if there’s any sort of standard for argument\_specs.yml-type documentation-as-code for Ansible collections and playbooks? I love that it’s implemented for roles and plugins but it really feels like collections and playbooks are kind of left to the developer’s interpretation. I don’t think there is. antsibull-docs can do this (same as for plugins and modules), but there are also other role-specific tools (I think). There are also elaborated tools (some of them have been around ofr quite some time) that create (or update in README) option tables based on default/main.yml, or maybe also other input than argument\_specs.yml. ---
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 16, 2024, 8:35pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/10 "2024-07-16T20:35:03Z")
> [@felixfontein](#): > > u can put a lot of stuff inside a table cell. That’s basically what antsibull-docs is using for the Sphinx output. For the ‘simplified RST’ outpu You can in fact have multiple paragraphs in one cell, you just have to put in some HTML style. But that still isn’t pleasant by any means in that fashion. But we have found the formatting capabilities within MKdocs-material has been quite amazing and awesome to work with. Will work with trying to work out mkdocs-ansible to see if it can auto-format everything. Maybe that will be something to be made if that package doesn’t do what is expected. ---
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 16, 2024, 8:35pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/11 "2024-07-16T20:35:48Z")
Overall, should we look at continuing to host our own documents for the modules? Or should we be looking to just point at the Galaxy documentation?? ---
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 17, 2024, 7:46pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/12 "2024-07-17T19:46:50Z")
I had been making some really good progress on getting what would be needed for a docs generation script. However, I’m running into the extension of other docs. Such as these: ```auto extends_documentation_fragment: - constructed - inventory_cache ``` I’m about to dive into the antsibull docs to see if I can decipher it. I have it parsing modules just fine and looking good. ---
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 17, 2024, 7:47pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/13 "2024-07-17T19:47:24Z")
If anyone else has some thoughts about this before I dig in, that would be helpful. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [July 17, 2024, 9:53pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/14 "2024-07-17T21:53:24Z")
@jvanderaa you really don’t want to parse documentation manually; use `ansible-doc --metadata-dump --no-fail-on-errors foo.bar` to dump all docs for all modules, plugins, and roles in the collection `foo.bar` as JSON and work with that instead. Also if you need to interpret Ansible markup (like `C(...)`, `M(...)`, etc) you might be interested in [GitHub - ansible-community/antsibull-docs-parser: Python library for processing Ansible documentation markup](https://github.com/ansible-community/antsibull-docs-parser/) if you’re using Python, or [GitHub - ansible-community/antsibull-docs-ts: TypeScript library for processing Ansible documentation markup](https://github.com/ansible-community/antsibull-docs-ts) if you’re using JavaScript or TypeScript. These zero-dependency libraries parse markup and have built-in functionality to convert it to MarkDown or RST or HTML, and make it easy to write conversion functions to other formats. ---
**Author:** ![isuftin\_at\_usgs](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/isuftin_at_usgs/32/925_2.png) [@isuftin\_at\_usgs](https://forum.ansible.com/u/isuftin_at_usgs)\ **Post date:** [July 18, 2024, 1:35pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/15 "2024-07-18T13:35:10Z")
Do you know where I can find more info on the usage of antsibull-docs-parser? The GitHub repo really only talks about installation. Is this utility useful for converting argument\_specs for modules and roles to markdown? ---
**Author:** ![samccann](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/samccann/32/18_2.png) [@samccann](https://forum.ansible.com/u/samccann)\ **Post date:** [July 18, 2024, 2:01pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/16 "2024-07-18T14:01:38Z")
> [@jvanderaa](#): > > Overall, should we look at continuing to host our own documents for the modules? Or should we be looking to just point at the Galaxy documentation?? My nickel is leave it to Galaxy if you do not have any extra guides (as in you have plugin docs and a readme). Galaxy will likely outperform your individual collection docsite on search results. But if you have user guides etc associated with your collection, Galaxy doesn’t really support that well, so you do end up needing a docsite for those. But that docsite doesn’t have to repeat the plugin docs that Galaxy already has. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [July 18, 2024, 4:22pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/17 "2024-07-18T16:22:07Z")
> [@isuftin\_at\_usgs](#): > > Do you know where I can find more info on the usage of antsibull-docs-parser? The GitHub repo really only talks about installation. Right now there is no documentation, but you can look at how it was integrated into various programs: - [Use antsibull-docs-parser to render semantic markup by felixfontein · Pull Request #88 · ansible-network/collection\_prep · GitHub](https://github.com/ansible-network/collection_prep/pull/88) - [Use antsibull-docs-parser to render semantic markup by felixfontein · Pull Request #28 · xlab-steampunk/ansible-doc-extractor · GitHub](https://github.com/xlab-steampunk/ansible-doc-extractor/pull/28) > [@isuftin\_at\_usgs](#): > > Is this utility useful for converting argument\_specs for modules and roles to markdown? It is useful for one very specific part of that, namely for converting one (or multiple) paragraph using Ansible markup to markdown. You still have to handle processing the argument spec and templating that somehow. ---
**Author:** ![felixfontein](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/felixfontein/32/7530_2.png) [@felixfontein](https://forum.ansible.com/u/felixfontein)\ **Post date:** [July 18, 2024, 4:24pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/18 "2024-07-18T16:24:19Z")
> [@samccann](#): > > My nickel is leave it to Galaxy if you do not have any extra guides (as in you have plugin docs and a readme). Galaxy will likely outperform your individual collection docsite on search results. Right now be warned that Galaxy does not render role argument specs (not sure whether there’s an issue tracking that, since galaxy\_ng does not use GitHub for issues), and it does not render documentation of plugins that use docs fragments from other collections ([Galaxy importer: collection dependency handling](http://forum.ansible.com/t/3496), no idea whether there’s anything in galaxy\_ng’s issue tracker for that either). ---
**Author:** ![jvanderaa](https://sea1.discourse-cdn.com/ansible/user_avatar/forum.ansible.com/jvanderaa/32/569_2.png) [@jvanderaa](https://forum.ansible.com/u/jvanderaa)\ **Post date:** [July 18, 2024, 5:55pm UTC](https://forum.ansible.com/t/mkdocs-for-docs/7283/19 "2024-07-18T17:55:33Z")
This is perfect @felixfontein - the part with the ansible-doc portion. That will get me a long ways down the road here. I had been working on some things with the help of LLM to do some parsing. But working from the structured data is going to be terrific. I will definitely be glad to share or help collaborate on enhancing it for others if those in the position of say are willing to accept another format.