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
• [x] 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.

[Naramsim]

Hi! Great job! I think you are re-using the already present JSONs. It's almost ready to be shipped. It's usable.

Some notes:

• in the Named and Un-named section, it would be cool to having listed all the supported paths, and then having them linked to the proper section.
• the JSON section could be reworked so to allow properties to be folded and hidden.
• I'd use fixed-width columns for the description of properties. The column header is always Name, Description, Type. So to have a bit of consistency for the width. A fixed-width expressed as a percentage, Something like 30%, 40%, 30%.
• We should be case-consistent in what's inside the parenthesis, for example (Endpoint) and (group).
• In this section I see the queryparameter not having the CSS code style. E.g.: ?limit=60
• I'd make the .right-sidebar-container closer to the right side of the screen and making the .main-pane larger.

One note: on https://pokeapi.github.io/pokeapi.co/v2/#pokemon-group if you scroll down to ability in the JSON file I see the property flavor_text_entries having unreadable characters. It's the same as in our current website. Could you polish the file? Both in this PR and in the main branch?

[Naramsim]

Hi @Indyandie how are you? I was wondering if you had some time to put into this :)

[Indyandie]

Hey @Naramsim I'm doing alright thanks for asking. I hope you're well too. I haven't made time but it's on my radar.