PokeAPI Docs V2

[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]

Hi! Thanks for the PR! The website looks amazing honestly. That said I think it was largely made by AI and there are many files to review. I'd rather like a simpler website with code easier to understand and less files.

I ping @Indyandie not for a review but to ask his opinion on whether this is maintainable or not. The first target that we should aim at is having something simple that everyone can understand easily and modify.

[FallenDeity]

Hi! Thanks for the PR! The website looks amazing honestly. That said I think it was largely made by AI and there are many files to review. I'd rather like a simpler website with code easier to understand and less files.

not a lot of it was ai generated most of the foundation of the website remains the same what indyandie had setup with almost no changes in logical part of it, most changes from my side came from styling parts of it inspired by shadcn/tailwind/mkdocs-material/fumadocs sites, some stuff i did use ai for was some of the client side js behavior like continuous scroll, and some footer logic etc

That said I do get the maintainence concern, imo most of the logical parts i.e astro and js is simple where it could get slightly complicated would be some of the starlight overrides I have in globals/guides.css which requires some amount of browser devtools inspection of elements to figure out class names and styles

for most changes however it should remain simple touching either of the following

• data json definitions
• how to guides which is just writing mdx files
• openapi is handled dynamically by pulling from master branch

[Indyandie]

Hi! Thanks for the PR! The website looks amazing honestly. That said I think it was largely made by AI and there are many files to review. I'd rather like a simpler website with code easier to understand and less files.

I ping @Indyandie not for a review but to ask his opinion on whether this is maintainable or not. The first target that we should aim at is having something simple that everyone can understand easily and modify.

@Naramsim right now I think this version is not maintainable for me. It would have been preferable if we had first address some of things we had been discussing.

[Naramsim]

What's this file for?

[FallenDeity]

applies styles and features to the starlight openapi plugin generated pages, like screen responsive dropdown/collapsibles for nested objects like past ability -> ability -> named api resource etc, headers for table/grid, badge themeing etc

[Naramsim]

I'm not favourable to this file. I'm ok shipping (or reviewing the PR without it first and then bit by bit enabling it) the the website without it.

Or maybe we can rewrite it in pure CSS? Not sure...

[Naramsim]

Yeah, thanks for your opinion!

Let's step back a bit. @FallenDeity if you are willing to rework a bit what you've done so to make it simpler that would help. Then gradually let's add all the features that @FallenDeity has added/in mind. The goal for the first version is to have code easy to read and having the features of the original website.

I'll list some points here in no particular order (part of the things listed here can be added later in separate PRs!):

• instead of using so much custom CSS we could rely on some standard CSS classes offered by Astro. No need to have fancy animations.
• No need for OG canvas
• Let's not use src/assets/endpoint-categories/*.png files. No need fo icons now.
• No custom Hero image. Let's hotlink everything.
• @FallenDeity can you investigate any alternatives to Koki? It's not that I don't trust @Indyandie (I trust you) but I'd rather go with something simpler and easier/community-tested. If nothing pops up, let's go with Koki but let's import it from NPM/CDNs, I don't want the code here.
• No custom continuous scrolling
• No latency badge
• No link to Slack
• No system status section. Just the badge linking to the statuspage is enough
• Leave only pokedex promise guide/comment the other two guides.

This is not a complain to what @FallenDeity has done, I'm really impressed by the outcome. I'm just trying to have something as maintainable as possible. Since our last website wasn't easy to maintain at all I'd go very careful here.

[FallenDeity]

converted to draft for future reference purposes

[Naramsim]

I pushed some commits @FallenDeity , you need to update the yarn lock

[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!