Pulling in pages from top level when using projects

[Krolken]

Hi.

I just signed up for insiders to try out if we can make our documentation handling a bit smoother using the projects plugin.
But I am running into some problems when I want to reference pages that are not in the project.

Our use case:
We have products and services that we deliver to our clients. Many clients will need the same type of documentation but we also document client specific things, lite settings and processes. So we would like to write some pages that are available to all clients and some pages that are only available to a single client.
We then build the documentation and deploy as a static web app on Azure with single-sign-on enabled to the client so it is secured for their personel. We want to use projects to keep a clients documentation so we can deploy that subfolder.
We also want to deploy all projects in our internal documentation so our personell can access all documentation.
We disable hoisting as we want each project to be separately deployable.

We want to write all common pages in a single place and then reference them in the nav settings of the customers project. So when we update a page, we don't have to do the same update for every client.

We don't want all clients to have access to all common pages as everyone doesn't buy/subscribe to all products and there is alot of customer specific pages anyway as everyone need to handle things differently.

I can't seem to get the linking of external pages in the projects dir to work. Any thoughts on how this can be accieved?
It seems like the project:// link annotation is not released yet, but would that render the page in the project or would it just link to another projects folder?

[squidfunk]

Thanks for trying out the plugin! Disclaimer: its still in experimental stage, and we're learning with our users, so your feedback is very valuable.

We disable hoisting as we want each project to be separately deployable.

Hoisting is only applied when you deploy the top-level project. If you build and deploy a subproject, the assets will not be linked from the top. Building and serving subprojects, they are always considered independent of each other.

We want to write all common pages in a single place and then reference them in the nav settings of the customers project. So when we update a page, we don't have to do the same update for every client.

It would be great if you could provide a minimal reproduction for this, so we can precisely understand your requirements and the directory layout you're aiming for. I'm confident that it is either already solvable with the plugin, or we can add additional functionality that will make it solvable.

I can't seem to get the linking of external pages in the projects dir to work.

Again, we need a reproduction. Without knowing exactly what you do, it is quite hard to help you.

It seems like the project:// link annotation is not released yet, but would that render the page in the project or would it just link to another projects folder?

You can use it in mkdocs.yml, but not yet in Markdown. However, we're close to finishing it, but haven't released it because we want to know exactly how users would use it. This will allow us to provide a solid implementaition.

[Krolken]

The linking problem is because it gets weird with absolute paths. I'll look into it more.

This is the folder layout we would like:

docs
 - shared_page.md
projects
 - first_customer
    - docs
     mkdocs.yml
 - second_customer
     - docs
     mkdocs.yml
mkdocs.yml

or we could have the common things as a separate project

docs
projects
 - common
   - docs
      - shared_page.md
   mkdocs.yml
 - first_customer
    - docs
     mkdocs.yml
 - second_customer
     - docs
     mkdocs.yml
mkdocs.yml

When we make the document structure we would like to be able to add the shared_page.md in the nav of both clients documentation.

[Krolken]

I made a minimal production of what I would like to do.

Currently build fails with Couldn't resolve project URL: paths currently not supportedas I want to use specific pages in nav.

minimal_reproduction_projects_with_shared_pages.zip

[squidfunk]

That's still not supported, but support is coming later ☺️

[squidfunk]

By the way, in the meantime, you should just be able to use relative or absolute URLs in nav. Support for resolving the final URLs of pages from *.md files will be tackled later. We have a prototype for this feature, but it's still unfinished.