Import a single file without creating a section

[froschdesign]

At the moment, only a section can be created during import. It would be great if an individual navigation entry could also be created without creating a section.

Current behaviour

nav:
  - Home: 'index.md'
  - MicroService: '!import https://github.com/…'

Results in

• Home (index.html)
• MicroService
  • Example (MicroService/example/index.html)

Expected behavior

• Home (index.html)
• MicroService (MicroService/index.html)

---

Maybe a new parameter is required for this and I think the title of the navigation entry with the !import statement should be used for the output.

Thanks in advance! 👍

[jdoiro3]

@froschdesign, I'll try to work on this change at some point this week. I'm still a little confused with this on my end. Could you provide another example or a public repo I can use for testing?

[rajiteh]

I have a similar need and wondering if I can use this plugin or some other combination of plugins to achieve what I need, essentially instead of dedicating an entire section in the top header for my imported repo I would like the imported docs to exist under a sub-path.

In other words let's say I have a structure like this:

index.md <-- home page
microservices/index.md <-- 'Microservices' is a section 
microservices/ServiceA/index.md <-- 'ServiceA' is accessed via the sidebar once inside 'Microservices'
microservices/ServiceB/index.md <-- 'ServiceB' is accessed via the sidebar once inside 'Microservices'

Now I want to host the docs for the each Service* in a dedicated repo, how would I import it in there?

Thanks for your time!

[jdoiro3]

@froschdesign and @rajiteh, I understand what you're both asking for now. I'll need to think through this and see what's the best way to approach this. Let me know if either of you have a chance to look at the source and have ideas.

[jdoiro3]

I'm doing some development in the dev branch and adding the ability to have an !import anywhere in the nav.

So in a parent repo you can have the below configuration.

nav:
  - Home: index.md
  - microservice:
      - Home: test.md
      - ServiceA: '!import https://github.com/jdoiro3/mkdocs-multirepo-demoRepo1?branch=main'
      - ServiceB: '!import https://github.com/jdoiro3/mkdocs-multirepo-demoRepo1?branch=main'

Which will build the navigation like this.

@rajiteh, is this what you're looking for? I'd like to make this plugin easy to use so feel free to provide any input.

[jdoiro3]

Also - trying to figure out the best way to import only a single file (or list of files) and allow for the imported docs to be used in the parent's nav.

@froschdesign, is this what you're looking for or not?

nav:
  - Home: 'index.md'
  - MicroService: 
      - Home: microservice/examples/index.md
      - 'API Examples': microservice/examples/api/sending_requests.md

plugins:
  - search
  - multirepo:
      # 'repos' is already used for importing docs without nav configuration. 
      # Not sure if this should be configured differently
      nav_repos:
        - name: microservice
          url: {url}
          # the plugin only downloads these files
          import: ['examples/index.md', 'examples/api/sending_requests.md']

[froschdesign]

@jdoiro3
Sorry for the late response, I was busy.

…is this what you're looking for or not?

This looks great and I like the idea of the file list for the import! 👍

[rajiteh]

Thanks, this is exactly what I was looking for as well. Appreciate the fast response!!

[wadimklincov]

@jdoiro3 I would find this really nice as well - especially if it could import things outside of docs_dir.

[froschdesign]

@wadimklincov
Please create a separate issue report for your feature request otherwise we will move further away from the original topic. Thanks! 👍

[DavidBuettner]

@jdoiro3 thanks for this plugin - I am also checking it out for different purposes. I especially like the import file list above. As an idea: could the file list also include folders, such that one can include a set of subfolders with all their content?

That would be especially useful, if the imported repository has different kinds of documentation in different folders, such as

• Developer documentation
• User documentation
• ...

Then a project which wants to combine all the user documentation of different projects could just import those parts without having to import all the files one at a time...

Thanks a lot!
Cheers
David

[froschdesign]

@jdoiro3
Do you need any more information from me? How can I help to make my original request a reality?
It would be great if a single file could be imported without creating a section. Nothing more is needed.

Many thanks in advance! 👍🏻

[jdoiro3]

@froschdesign, been busy with work and other stuff the past few months. The next time I devote time to this project I will look into implementing this feature.

[jdoiro3]

Finally started working on this. Draft PR is #80.

[jdoiro3]

@froschdesign, feel free to install this branch and try out the new feature. I'd like to confirm it meets your requirements before preceding.

Here's an example:

site_name: Mkdocs Multirepo Plugin Example

plugins:
  - search
  - multirepo:
      nav_repos:
        - name: backstage
          import_url: https://github.com/backstage/backstage
          imports: [docs/publishing.md, docs/integrations/index.md, README.md]
        - name: fast-api
          import_url: https://github.com/tiangolo/fastapi?docs_dir=docs/en/docs/*
          imports: [docs/en/docs/index.md]

nav:
  - Home: backstage/README.md
  - Integration: backstage/docs/integrations/index.md
  - Publishing: backstage/docs/publishing.md
  - FastAPI: fast-api/docs/en/docs/index.md=

[jdoiro3]

Closing b/c v0.6.0 should have resolved this.