Documentation site - niggly issues

[chrisk-7777]

Hello,

I've been doing a quick spike locally to see if I can address a few niggly issues on the docs.
They don't have issues in the backlog, but they are pretty minor, so I thought it wouldn't hurt to raise.

They are:

• Having a fixed sidebar on the left with its own scroll
• Having a sidebar on the right with the sections of the current page (like: https://vitest.dev/guide/)
• Fixing the mobile menu. Atm, the mobile nav is broken - it doesn't navigate on mobile from the dropdown. Minor, but you know, who doesn't like reading the Excalibur docs on the train?

Before I go down that rabbit hole, I was wondering if the core team had considered something like docusaurus that handles a lot of that out of the box?

Obviously any change as fundamental as the framework running the site is not to be made lightly - so in no way am I suggesting that should be the direction! More so curious on the overarching direction of the docs.

But... just for fun, I threw the first few pages in a docosaurus site:

[eonarheim]

@chrisk-7777 We have been talking about changing our tech here, nothing has really solidified yet. Docusaurus looks pretty dope, just watched some videos about it and it checks a lot of boxes!

In general I'll support anything that makes it easier to contribute and maintain (the current gatsby setup is a little tough).

@kamranayub @jedeen I'll defer to you on doc site changes! What do you think?

• Do we need to port the custom plugins to get typedoc linking?
• Anything else that's custom that we'd really want to have?

[kamranayub]

I'm in support of Docusaurus, it's at the top of my contenders. The major custom thing that needs to be ported in any case is API reference links. Gatsby made that a bit easier with the source plugin architecture. I haven't looked at what it would take for Docusaurus.

We also have some custom MDX components I think that would need to be ported.

There's a few other providers like Mintlify I was researching too, but we want it to be seamless for contributors and we don't have a budget to pay for hosting docs.

Keep in mind too whatever we switch to needs to support having other pages, like the homepage, gallery, etc. With Gatsby, we have total flexibility but obviously that comes at the cost of not having a lot of the docs niceties out of the box.

[chrisk-7777]

Thanks for having a read. I'm not strongly pushing for Docusaurus, more how to best apply my efforts based on the overall direction. However I'm glad to hear its at the top of your list too!

If there is anything I can do, in way of spikes, or other investigation, to help further the decision, do let me know.

[kamranayub]

I've created an issue to track the rewrite: excaliburjs/excaliburjs.github.io#383

[chrisk-7777]

Closing in favor of excaliburjs/excaliburjs.github.io#383

Thanks Erik and Kamran !

[eonarheim]

Not sure if we posted the link, but you can check out the in progress site here! https://excaliburjs.pages.dev/