404 on all docs on fresh install

[andyhasit]

Can't seem to accept the discord invite so asking here.

I'm trying to create a github pages using astro, and decided to add the starlight package following the manual setup. I apparently require a base for astro to work with github pages (and that seems to work, prior to adding starlight).

Here's the branch on my repo with very little in there other than dummy content: https://github.com/wallace-js/wallace-js.github.io/tree/starlight#

I'm getting two errors, the first being this one when I so much as hover over <a href="docs">Documentation</a>:

TypeError: Cannot read properties of undefined (reading 'hidden') at /code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/navigation.ts:241:44 at Array.filter (<anonymous>) at treeify (/code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/navigation.ts:241:4) at getIntermediateSidebarFromConfig (/code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/navigation.ts:398:16) at getSidebar (/code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/navigation.ts:372:25) at generateRouteData (/code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/routing/data.ts:52:18) at useRouteData (/code/wallace-js.github.io/site/node_modules/@astrojs/starlight/utils/routing/data.ts:40:20) at /code/wallace-js.github.io/site/node_modules/@astrojs/starlight/routes/common.astro:18:46

Which, following the stack trace, seemed to indicate sidebar is undefined in @astrojs/starlight/utils/navigation.ts:241:

.filter((doc) => !doc.entry.data.sidebar.hidden)

I can temporarily get rid of the error setting an empty array in my config:

// @ts-check
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

// https://astro.build/config
export default defineConfig({
  site: "https://wallace-js.github.io",
  base: "/wallace/",   // apparently required for github pages
  trailingSlash: "ignore",
  integrations: [
    starlight({
      title: "Wallace",
      // sidebar: [],   // This disables the error.
    }),
  ],
});

But that leaves me with the second error (or maybe this is the primary error masked by the first) which is a 404 going to http://localhost:4321/wallace/docs even though I do have this file with contents as per the guide:

site/src/content/docs/index.md

Interestingly, if I rename that file to index.astro, I don't get the error, just the 404. I've been clashing heads with chatGPT for an hour on this (I don't normally lean on AI but thought I'd give it a shot for this) to no avail. I've been deleting the cache and re-running and trying various permutations of trailingSlash , removing the site/src/content.config.ts file etc... but totally stuck getting something so simple to work.

[HiDeoo]

Thanks for the report 🙌

Sharing here our Discord URL in case you may not have been using the correct one: https://astro.build/chat/

I guess there are 2 issues at play here:

a 404 going to http://localhost:4321/wallace/docs even though I do have this file with contents as per the guide:

As mentioned in the "Add content" section of the getting started guide, Starlight content is located in the src/content/docs/ directory.

You do indeed have an index.md file in site/src/content/docs/ directory, but you also have a site/src/pages/index.astro file that is taking precedence over the content route. Deleting the site/src/pages/index.astro file and visiting http://localhost:4321/wallace/ does load the Starlight content as expected.

If you only want your Starlight content to be available at http://localhost:4321/wallace/docs and keep the site/src/pages/index.astro page, you would need to follow the "Use Starlight at a subpath" guide and use an extra docs subdirectory inside the src/content/docs/ directory. For example, your index.md file would need to be located at site/src/content/docs/docs/index.md.

I just tested locally and can confirm that both approaches work as expected.

I'm trying to create a github pages using astro

I am not a GitHub Pages expert, but it looks like you are not using the documented and recommended approach to deploy an Astro site to GitHub Pages. I would highly recommend following that guide to set up your deployment correctly.

If it can help, I'm also sharing this repository which uses Starlight and is deployed to GitHub Pages, you can maybe also check its configuration for reference if needed.

[andyhasit]

Wow, thank you so much for doing all that. The nested docs within docs structure gives me what I need, and the github pages guide indicates I should not be setting a base if using a custom domain, which I will be, and would have totally missed that otherwise.

Faith in Astro restored 🚀🚀🚀