Refactor for multiple docs plugin instances and sidebars#48
Conversation
|
Your pull request has been made available for preview at: |
|
After conversation on discord, this isn't preferred. |
|
I think there shouldn't be a global sidebar. There are few cases where, in one session, one is jumping about between different platforms' admin docs and developer docs. I think there should be 3 sidebars, one for each platform, and then for each platform, there is two top level sidebar entries, one for server admins, one for developers. and a landing page that just has a small blurb about each platform and links to the admin/dev page for that platform |
|
Made a bunch of changes to sorta match that. Now: Four total sidebars:
With this also comes wayyyy more URL changes, so more redirects to add once this is done. |
currently in cloudflare pages/netlify format. may change depending on eventual deployment decision
|
Looks good. couple inconsistencies with sidebar item naming and such, but the structure looks good. I think the Welcome pages need to be renamed or have a different name template, |
|
Yeah, buttons would be nice. I had investigated this when initially implementing them, using the built-in DocCards - however, it's not feasible to autogenerate this as global sidebar state isn't available here at mdx compile time. So essentially, it'd either have to be hacked together with some weird post-processing or done manually, which are both far from ideal. I'll further investigate the post-processing possibility as it would be a significant improvement. |
|
I've gone for a different approach and instead added these link items to each category (admin/dev) and made that the main landing page from the navbar. An issue I've noticed is that the |
|
Happy enough with the organization here now. Still have to work on some UI issues, but that can be done as a separate PR. |
Also see #50 for an alternative idea.
Refactor to separate the different projects more, both in terms of the sidebar and how they are dealt with internally. It does not break URLs, though, outside of the
papermcgroup, which has been moved intocommon.This is mostly just experimental/a concept. I'm still pretty much 50/50 as to if this is better or not. Mostly open for feedback. This isn't complete.
Some advantages that this does provide, more for the future:
Should we want to implement versioning, Paper and Velocity could be versioned differently, while Waterfall/Common wouldn't need to be versioned at all.
Localization would also be cleaner to implement, should we want that.
Something applicable now is changing all of the sidebars to be independent. You will now only see the sidebar for the project you are browsing. This is doable without different
content-docsplugin instances for each set of docs, but I figured why not just get that out of the way now, so it is less pain should we want to version later down the line.A limitation of this with the current architecture of Docusaurus, you can't use markdown links between docs in different sections. You instead need to link to its slug (see the java update guide link changes). This has no change in the built site but is slightly more work in writing docs. This would be solved by something like this proposal. The same applies to
docsidebar link types. Alinktype would be required instead.Todo:
getting helpsection (under common) and add to the top of each sidebarcommonwill still display all results.