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 instead of having all the icons here I'd rather hotlink the ones that we are serving from the API, and for the pokeapi logo you could hotlink the images in the media repository.

[FallenDeity]

mhm will make that change

[Naramsim]

How did you generate these images?

[FallenDeity]

A python pillow script for one time generation

[Naramsim]

What's koki?

[FallenDeity]

koki is whats used under the hood for the json tree visualizer in api explorer its what indyandie had been using

[Naramsim]

I see a log of CSS here and somehwere else. Can we put everything in a CSS file?

[FallenDeity]

hmm I inlined the css after seeing the addition of tailwindcss wherever possible while keeping the css files largely limited to starlight style overrides for a clearer distinction bw css

imo this is a trade off bw development speed and being able to style directly in the html file vs having too switch bw css files and look up stuff via class names tailwind also helps with purging unused css/styles and future changes are scoped and easy to review

that said if some styling is too complex we can perhaps use the @apply directive for longer lines

[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