Natural path structure for hono.dev

[goisaki]

Currently, hono.dev is configured like this:

• /api
• /concepts
• /guides
• /helpers
• /middleware
• /snippets

I would like to change this to this configuration:

• /docs/{api,concepts,guides,helpers,middleware}
• /snippets

old:

• /api
• /docs/{concepts,guides,helpers,middleware}
• /snippets

This will give us this benefit:

• Natural structure
  • For example, in Guides, the web structure is in Docs, but the folder/path structure is not.
• The mysterious top.md is no longer needed (it can be index.md)
• The honojs/website directory will be cleaner.

These disadvantages are expected:

• Old URLs will die.
  • It will be easy to fix URLs in official repositories
  • Third-party old links can be solved by adding redirect handling
• The flat directory structure (for the most part) of honojs/website will be lost

@yusukebe @sor4chi @ryuapp and others Let me know what you think.

[ryuapp]

That's a good idea.
It would be even better if /docs includes api slug.

If we just use hono.dev for documentation, we might be able to leave it as is, but I prefer this structure.

[goisaki]

@ryuapp, thanks for responding!

It would be even better if /docs included the API slug.
I considered that as well, and I agree it's a good idea.
However, I believe most Hono developers, especially those still in development, would be more interested in "API" rather than "Get Started". Therefore, I thought they would prefer having an API link in the navbar, which is why I didn't include it in the docs.
Both suggestions have merit, and I would love to hear more opinions on this.

[MathurAditya724]

We can also unify the snippets and docs sections in a single sidebar and remove them from the top right navbar. It becomes quite confusing navigating between these two until you notice.

I also agree that the /api should be included in /docs

[goisaki]

@MathurAditya724 thanks for responding!

We can also unify the snippets and docs sections in a single sidebar and remove them from the top right navbar.

I see. I agree that it can be confusing.
However, Docs and Snippets have too much different content and I don't think that is a good solution.
How about combining Snippets and Examples into one with a drop down menu?

[MathurAditya724]

Not sure about how It will look with a dropdown but merging them sounds great.

[NicoPlyley]

I noticed this the other day when in the docs. I don't think it makes a big difference besides preference. If it were to be merged into /docs (I think API should be included) redirects are an absolute must. There are so many questions answered with links to docs. Every time I add a code solution, I comment the docs link to what I am referencing.

If the change is made I think we would just have to add /docs/ in front of all pages except snippets. It would clean up the file structure a bit too. But that means keeping prefixes like /helpers so it would become /docs/helpers. The reason for this is there are some pages with the same name, and the URL makes it clear what page we are working with. For example, there is: /helpers/jwt and /middleware/jwt.

Ultimately the decision is prefence at this point. If there are plans to expand the Hono website, I think it would be smart, but only if redirects are setup for all existing routes that would be changed.

[goisaki]

@NicoPlyley thanks to responding!

If the change is made I think we would just have to add /docs/ in front of all pages except snippets.

I have found that many people share this opinion and would like to see this implemented.
I understand the value of linking to existing documentation (which has been helpful to me many times), so I will add the redirect as well.

Ultimately the decision is prefence at this point.

Agreed. I would love to hear @yusukebe's opinion.

[yusukebe]

@goisaki

Thank you for your suggestion! Regarding this issue, I want to leave much of the work to you.

Actually, I've referred to the Bun's website when I was building our website:

https://bun.sh/

You can also refer to it. Our Snippets is the section called the Guides on Bun's website.

[goisaki]

What great news! I'll start working on it.

Through this discussion, we have found other improvements to hono.dev not just the path structure.
Considering that we will also make changes to these as well, hono.dev may be incomplete during the modification process.
So like the version up of honojs/hono, I want to work on the next branch for now.
To explain more, there will be these ways:

1. small PRs -> next -> main (my opinion)
2. small PRs -> main

@yusukebe, which is the better way?

[yusukebe]

1. small PRs -> next -> main (my opinion)

I like it!