new Astro docs roadmap

[Naramsim]

Hi @Indyandie , I'll write here a checklist of required and optional things (that I see as of now) to do in order to move from our current website to the Astro one:

• import all the API v2 sections as they appear now (https://pokeapi.co/docs/v2). Or find a way to have the same info on the OpenAPI section. One thing that the OpenAPI section seems to be lacking is the the types of the objects
• The front-page try-it-now

Optional:

• A translation system
• A section for writing how-to guides

[Indyandie]

Hey @Naramsim, thanks for putting this together.

1. Can you help outline a check list of the things we'll need for API v2 sections to be represent accurately. We might be able to just update the openAPI spec, but if not we could just recreate what's there at the moment.
   • Maybe we could use berries as an example.
     • Berries Section (Current Site)
     • Berries Tag) (New Site)
     • First thing that jumps out is that missing descriptions in the response
2. Try it now should be fairly simple.

Optional

1. Starlight supports i18n. I think this might be bigger project.

• Do we have any translations at the moment?

1. The Step component could come in handy for writing how-tos.

[Naramsim]

Regarding 1. I think many things are missing. For example:

• The reference returned JSON
• The description for each property
• The basic types. i.e.: the flavors for the berries are typed as list BerryFlavorMap and in the Astro one is simply Array<object>. But it's cool that you can click and see how the object is composed. But if you click too many nested properties it might become overwhelming, maybe.

Some things we need to rework

• The API doesn't have any kind of authorization, so listing everytime CookieAuth, BasicAuth, None is useless. It's hardcoded api.example.org.
• In the pokemon section there's references to ability_list and ability_retrieve.
• We should order everything alphabetically
• Remove the bottom buttons to navigate to previous and next resources. Imho are not useful
• We might as well get rid of the right hand side column On this page. So we have more space for actual content. Or maybe show it only on large screens. On my 13" everything is a little crammed.
• The application/json select is also useless. (We could hide as well the 200 status code.)
• I like the continous scrolling of CloudFlare. i.e.: https://developers.cloudflare.com/api/resources/accounts/methods/create/ SO for the berries one could scroll all the way from Overview to Get berries by flavor. As it is in the current website.
• I think CF documentation is a good place to look at for suggestions. And I think they use Astro as well.

[Naramsim]

Hi @Indyandie , I just wanted to check if you saw my message, no stress. If you don't have time to update the code there's no problem!

[Indyandie]

Hi @Naramsim , thanks for checking in. It’s on my radar, and I’m still figuring out the best approach. I’ll follow up once I’ve got a solid plan together.

[Indyandie]

@Naramsim The try it now section has been added to the home page. The most obvious thing that's missing is the copy to clipboard button. I'll work on that next.

Let me know if you have any feedback or questions.

[Naramsim]

Hi! Great addition! I would be perfect if a user could click them and the request would fire immediately.

[Indyandie]

@Naramsim

• Click them? Can you share an example?
• What browser are you using?

[Naramsim]

Something like we already have:
https://github.com/user-attachments/assets/2a759656-466c-44e1-bef9-aca6d14d85df

When clicking on a resource the call is fired and the content is updated. In the video I'm clicking on the various examples

[Indyandie]

Oh I see, clicking on the hints. I should've tested. 😆

Thanks @Naramsim, that should be pretty simple to update.

[Indyandie]

@Naramsim the try it now section should be good to go now. Let me know if you have any feedback. https://pokeapi.github.io/pokeapi.co/

[Naramsim]

It works! Thanks a lot!

[Indyandie]

@Naramsim hope this find you well!

I finally made some time to update the v2 page with the resource data. Let me know what you think.

Now that I'm more familiar with the info in the JSON files I can try to move some of it the OpenAPI spec into the main repo.