backstage/mkdocs-monorepo-plugin

BUG: Edit URI of !included mkdocs.yml not respected when building pages

egnwd opened this issue · 8 comments

egnwd commented

Expected Behaviour

When creating documentation with the monorepo plugin I expect to be able to include sub-documentation and have the edit link on the final page be correct.

Current Behavior

When I load a page generated from the sub-documentation the ✏️ Edit link is incorrect, taking me to a 404.

Steps to Reproduce

I've added a sample docs folder that reproduces this issue.

  1. Checkout to this branch
  2. cd __tests__/integration/fixtures/bug-include-path-edit-uri
  3. npx @techdocs/cli build
  4. Inspect the index.html and test/index.html generated in the site folder

The top level docs is correct, the edit url generated is: https://github.com/egnwd/mkdocs-monorepo-plugin/edit/bug-edit-uri/__tests__/integration/fixtures/bug-include-path-edit-uri/docs/index.md
The sub-docs is incorrect, the edit url generated is: https://github.com/egnwd/mkdocs-monorepo-plugin/edit/bug-edit-uri/__tests__/integration/fixtures/bug-include-path-edit-uri/docs/test/index.md

Note the ending should be .../api/docs/index.md but is .../docs/test/index.md which is its location once the merger has aggregated the folders and named them after the site_name.

egnwd commented

Just seen that this is likely a duplicate of #2, but I'll leave it open as I do believe this is a bug and not many details were added to the other issue - but happy to be told otherwise

marc0olo commented

@emmaindal I commented on #2. I really like this plugin but I need to be able to display the correct edit url for the submodules I have included.

I see you added the help wanted label. I haven't checked the code yet. could you shortly summarize what needs to be done to get this working? have you already had a look into the issue?

iamEAP commented

could you shortly summarize what needs to be done to get this working?

Hey @marc0olo! Appreciate your willingness to help out on this. Here's my understanding of how things work:

  • Per these docs, mkdocs just smashes together the repo_url and edit_uri to generate the final edit URL.
  • This "smashed together" URL materializes as page.edit_url in the theme per these docs, which is what gets printed out.

Given the above, it makes sense that sub-documentation gets a broken URL because the repo_url and edit_uri are fixed configs at the root mkdocs.yml. To work around this, we'll need to do a couple of things...

  • Maintain knowledge/state of the sub-documentation directory structure somewhere in the plugin (or perhaps a temporary file or keys on yaml--this state may already be kept track of somewhere, I haven't touched this code in... well, maybe ever)
  • In the on_pre_page hook, modify page.edit_url according to the current page and that sub-documentation directory structure state from above. See on_pre_page docs here.

I would also highly recommend cherry-picking @egnwd's test fixture commit and adding a test case in test.bats in the integration tests folder.

Hope that's enough to get you started!

emmaindal commented

Based on the information @iamEAP has provided, is this issues something you would like to pick up? @marc0olo
I've not looked into the problem myself yet but we will do, just wanted to check in with you first! If you want to work on it let us know and we can assign you to the issue.

marc0olo commented

hey @emmaindal, currently I don't have a plan to cover this. decided to go another route finally as we had more important stuff to focus on

emmaindal commented

Totally understand @marc0olo, we will pick this up in our team. Thank you!

camilaibs commented

Closed by #74

  • 🚀2
G-man83 commented

Steps to Reproduce

I've added a sample docs folder that reproduces this issue.

1. Checkout to [this branch](https://github.com/egnwd/mkdocs-monorepo-plugin/tree/bug-edit-uri)

2. `cd __tests__/integration/fixtures/bug-include-path-edit-uri`

3. `npx @techdocs/cli build`

4. Inspect the `index.html` and `test/index.html` generated in the `site` folder

The top level docs is correct, the edit url generated is: https://github.com/egnwd/mkdocs-monorepo-plugin/edit/bug-edit-uri/__tests__/integration/fixtures/bug-include-path-edit-uri/docs/index.md The sub-docs is incorrect, the edit url generated is: https://github.com/egnwd/mkdocs-monorepo-plugin/edit/bug-edit-uri/__tests__/integration/fixtures/bug-include-path-edit-uri/docs/test/index.md

Note the ending should be .../api/docs/index.md but is .../docs/test/index.md which is its location once the merger has aggregated the folders and named them after the site_name.

I have followed the above repo steps and it is still generating the incorrect edit_uri (as above).

@iamEAP @camilaibs is it possible that this has regressed?

Note, the @techdocs/cli --version is 1.4.5