[FallenDeity]

Hi folks opened a pr for review and discussion purposes for the docs website migration

Astro + Starlight based docs (refer to #162)

This pr migrates the old react static based docs to astro based docs initially setup by @Indyandie this builds on top of that to add more features

The site is hosted on https://fallendeity.github.io/pokeapi.co/ currently available for active review and open for revisions required for any unexpected logic or visual bugs

file structure

├───assets
│   ├───endpoint-categories
│   └───og
├───components  (contains component astro/js/css files)
│   ├───explorer
│   ├───footer
│   ├───header
│   └───markdown
├───content  (markdown content to be expanded in future for i18n)
│   └───docs
│       ├───how-tos
│       └───v2
├───data  (our endpoint documentation jsons)
│   └───operations
├───pages  (opengraph metadata generation endpoint)
│   └───og
└───styles  (global styles)

Known issue package.json ghpages command site url env var currently for review purposes points to fallendeity.github.io and openapi schema url in astro config waiting on this to get merged for latest openapi PokeAPI/pokeapi#1609

attempt has been made to utilize tailwindcss for most styling the remaining styling overrides the starlight styles used by starlight during build time to fit the theme and ui

Pic Gallery

cc: @Naramsim @Indyandie

[Naramsim]

Some comments:

• The favicon looks streched on my local dev
• I'd like to shrink a bit the right column (On this page)
• When clicking on a how-to-guide the CTRL K in the search bar looses some CSS

Great job @FallenDeity ! You updated the code just as I wanted! :) We can ship the new website soon I guess!

[FallenDeity]

@Naramsim made rest of the changes u mentioned and few more cuts to some bloat we had with footer styling and some extra astro files consolidated them, also changed the color palette a bit

also added alert capabilities same as old site

[Naramsim]

Hi, some comments:

0. on the apiv2, the explorer codeblock some times is unnecessarily big, take a look at Berry Firmnesses (Endpoint)
1. can we have the text of the try-out searchbar as a placeholder?
2. the back-to-top button (when scrolling close to the end of the page) giggles up and down too much. It tryes to stay on top of the footer but it lags. We can just have the button with a fixed position.
3. in the openapi page we have all the parameters limitations such as >= -2147483648 or <= 200 characters. We can hide them since they are just a distraction with numbers that nobody cares.
4. for some resources we still have the default example: https://fallendeity.github.io/pokeapi.co/v2/openapi/operations/berry_list/ we can either fix it in the upstream schema file or hide the Example section until is resolved.
5. for the switch theme i'd put a Lunatone/Solrock of DreamWorld or Home 3D scaled at 0.9. It looks better and less pixellated?
6. on Mobile the UI is a bit too cramped up, for the apiv2 we might need to maybe hide a column for the properties descriptions.

Excellent work for the rest! We are close to ship this! Imho the blockers are number 3 and 4

[FallenDeity]

updated with the changes except for 0 and 1 (for one i sent a message on discord) regarding 0

its because the payloads u see embedded on load are trimmed payloads to keep webpage size small, if the user hits a req then they get the full payload and u will see the scroll i could make the sizes smaller for all of them but then it would be a lot more scrolling, if i make it different size per endpoint it wouldnt match size based on endpoint they fetch or i would have to resize when they fetch causing a layout shift which is jarring, i think current size is fine we can tweak it a bit later

[Naramsim]

Hi, regarding 0 I meant that instead of writing directly inside the api explorer input, we could use the HTML property placehoder. So that when one clicks the input the user can start typing right away the resource he wants to query.

Here an example of api-explorer with the string 35 already filled in, if a user wants to use the functionality he has to first remove the 35 and then input what he wants. Same goes for the front page one.

If a user fires the request without submitting a string we could either show a message or do nothing since the result has been already loaded.

[Naramsim]

One minor thing, when clicking the blue button Send, the button resizes and the text changes to ... becoming a square for some milliseconds. Can we maintain the same size?

I think the following CSS fixes what I'm saying:

.explorer-send-btn {
  width: 95px;
  display: flex;
  justify-content: center;
}

PS: to see what I'm talking about you can slow down your network in the console panel and you'll see the button resizes until the request is done.

[Naramsim]

@jemarq04 @phalt could you review this one? we are ready to publish to prod

[FallenDeity]

I think we should get this in first before the site PokeAPI/pokeapi#1711 it fixes some of the openapi schema inconsistencies we had and if this is merged it would allow me to drop some of the processing and workarounds here