Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO NOT MERGE]: POC: DocNavbarItems link across instances to the correct version #1345

Closed
wants to merge 3 commits into from

Conversation

pepopowitz
Copy link
Collaborator

@pepopowitz pepopowitz commented Oct 6, 2022

What is the purpose of the change

This is a POC PR, demonstrating how we could fix #1333.

I say "could" because there is risk associated with this fix -- we're overriding multiple internal functions for this component, which is unsafe in the sense that docusaurus has no obligation to let us know when these things change/break. A future minor/patch version update of docusaurus could leave us with broken code, and/or we will likely spend time in the future rewriting our overrides based on the updated internals.

I also don't know if we've determined how much of a problem #1333 really is - it certainly annoys me, but it might be an edge case that no one but me runs into.

Video demonstrating the problem, the source code responsible for it, and the fix: https://www.loom.com/share/ea910112df7643b4856ed60c93105157

What's going wrong?

When browsing a document within Optimize, Docusaurus is trying to identify which version you want to see for the top nav links, but it's basing it on where you were within the main docs, instead of where you currently are.

How does this fix it?

This PR swizzles the DocNavbarItem component, so that we can write our own version of useLayoutDoc, so that we can write our own version of useDocsVersionCandidates.

More detailed comments are in the code.

Are there related marketing activities

No

When should this change go live?

🤷 should it go live?

PR Checklist

  • My changes apply to an already released version, and I have added them to the relevant /versioned_docs directory, or they are not for an already released version.
  • My changes apply to future versions, and I have added them to the main /docs directory, or they are not for future versions.
  • My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
  • My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

@pepopowitz pepopowitz added component:docs Documentation improvements, including new or updated content dx Documentation infrastructure typically handled by the Camunda DX team epic:optimize-versions labels Oct 6, 2022
@pepopowitz pepopowitz self-assigned this Oct 6, 2022
Copy link
Member

@akeller akeller left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love this because I don't like having to go into the guts of a platform to do anything. That said, if everything is "contained" to this single file, we know what to rip out if/when this breaks in the future.

I want to drag my feet on this a bit and see if we get feedback first.

@pepopowitz
Copy link
Collaborator Author

I want to drag my feet on this a bit and see if we get feedback first.

I'm on board with that. I'll close this out and if we get feedback we can revisit.

@pepopowitz pepopowitz closed this Oct 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component:docs Documentation improvements, including new or updated content dx Documentation infrastructure typically handled by the Camunda DX team epic:optimize-versions
Projects
Status: ✅ Done
Development

Successfully merging this pull request may close these issues.

bug: non-Next versions of Optimize documentation link to incorrect version of main docs in header
2 participants