How can this plugin be better?

[jdoiro3]

👋 Hey!

First off, thanks to everyone trying out this plugin and creating issues to make it better! A few have suggested changes (e.g., issue #11) and since I'd like to make sure the configuration is intuitive and the plugin useful for everyone, I'd like to see if anyone else has thoughts or suggestions. Feel free to comment below with something along the lines of:

• Using this plugin would be easier if _____
• I'm confused by _____
• This plugin would be better if I could _____

[froschdesign]

I'm confused by the multiple question marks in the URL:

'!import {url}?branch={branch}?docs_dir={path}?multi_docs={True | False}?config={filename}.yml'

The question mark is used as a separator for the query string in a URL. But here it is also used to separate query parameters, instead of the ampersand &.

---

This plugin would be better if I could specify the imported files, e.g.:

import: ['examples/index.md', 'examples/api/sending_requests.md']

---

This plugin would be better if the imported directories had URL-friendly names, see #24.

---

This plugin would be better if I could import a single file without creating a section, see #11.

---

This plugin would be better if tags can be used instead of branches. With support of ?tag=latest

[jdoiro3]

@froschdesign, I just created a pull request (#27) to address an !import statement's query string. Can you confirm this change is what you're requesting? I also have a pull request for issue #24.

[nejch]

Just wanted to join in on the discussion, I'll try to collect more feedback and formalize it according to your template but a quick dump for now:

• @froschdesign IMO branch can just be renamed to ref, because it just does a checkout behind the scenes - it actually already works with any ref, so branch=v1.0.0 and also with commit hashes. branch already works with tags, but not hashes as I originally thought :) We plan to use this to pin & bump them explicitly with renovate.
• It would be great if no mkdocs.yml was required for the nav-based import and just take the tree structure as well: for some use cases it would simplify dependency management and only manage mkdocs in the root repo.
• minor nitpick: as a potential contributor I was surprised to see the embedded bash scripting, I assume this could all be done in python but I understand that bash is more concise. mike, which does similar things during build for versioning, does a lot of git in python though.
• some sub-repos might be using plugins and this currently needs to be manually added/tracked in the root repo.

[oleg-nenashev]

I am tinkering with the plugin, and it looks really good for our use-cases. After some evaluation I lean towards adopting MkDocs + Multirepo-Plugin + Material for MkDocs in WireMock, because we would like to offer Antora-alike experience to the community mostly using Markdown at the moment (FTR wiremock/wiremock.org#24). And the combination is a great start, and I was surprised how smootly the combination worked.

There is a lot that could be done to make it on par with Antora, and I hope to contribute a few features to the plugin. Some items on the top of my list:

• Cross-link resolution: replacing GitHub links by relative links when both repositories are included
• Better DevX, especially limiting unnnecessary fetches on bigger repositories when developing docs. Right now live reload is quite impacted by the plugin, though I hope to contribute a patch