Skip to content

Refactor for multiple docs plugin instances and sidebars#48

Merged
e-im merged 19 commits into
PaperMC:split-projectsfrom
e-im:refactor-docs-plugin
May 29, 2022
Merged

Refactor for multiple docs plugin instances and sidebars#48
e-im merged 19 commits into
PaperMC:split-projectsfrom
e-im:refactor-docs-plugin

Conversation

@e-im
Copy link
Copy Markdown
Contributor

@e-im e-im commented Apr 4, 2022

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 papermc group, which has been moved into common.

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-docs plugin 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 doc sidebar link types. A link type would be required instead.

Todo:

  1. Create a proper getting help section (under common) and add to the top of each sidebar
  2. Use search facets to limit search to the project you are currently viewing (with a toggle?) and common. Homepage search or search on common will still display all results.
  3. Other things I am forgetting now, I know I had way more than this when I started to type out the comment. I'll update this

Comment thread config/common.ts Outdated
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 4, 2022

Your pull request has been made available for preview at:
https://papermc.github.io/docs-previews/pull/48/
Last deployed: b202836.

@e-im e-im marked this pull request as draft April 6, 2022 00:02
@e-im
Copy link
Copy Markdown
Contributor Author

e-im commented Apr 9, 2022

After conversation on discord, this isn't preferred.

@e-im e-im closed this Apr 9, 2022
@e-im e-im reopened this Apr 10, 2022
@Machine-Maker
Copy link
Copy Markdown
Member

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

@e-im
Copy link
Copy Markdown
Contributor Author

e-im commented Apr 10, 2022

Made a bunch of changes to sorta match that. Now:

Four total sidebars:

  1. Paper
  2. Velocity
  3. Waterfall
  4. Common

paper and velocity sidebar are split into admin and dev, while waterfall and common sidebars are unified (waterfall does not have a dev section).

With this also comes wayyyy more URL changes, so more redirects to add once this is done.

@e-im e-im marked this pull request as ready for review April 10, 2022 20:37
@Machine-Maker
Copy link
Copy Markdown
Member

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, Welcome to Blah seems too long, and repetitive, idk what the best solution is, just Welcome or Paper/Waterfall/Velocity. I think the welcome pages should also have big button links to each top and 1-level below section of their sidebars, or at least if the sidebars can be expanded on page load.

@e-im
Copy link
Copy Markdown
Contributor Author

e-im commented Apr 16, 2022

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.

@e-im
Copy link
Copy Markdown
Contributor Author

e-im commented Apr 16, 2022

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 activeBaseRegex does not seem to correctly apply for the dropdowns themselves (although for its items, it works perfectly). I've also yet to update the home page.

@e-im e-im changed the base branch from main to split-projects May 29, 2022 00:46
@e-im
Copy link
Copy Markdown
Contributor Author

e-im commented May 29, 2022

Happy enough with the organization here now. Still have to work on some UI issues, but that can be done as a separate PR.

@e-im e-im merged commit 14f04d7 into PaperMC:split-projects May 29, 2022
@e-im e-im deleted the refactor-docs-plugin branch May 29, 2022 00:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants