gatsby-theme-apollo
gatsby-theme-apollo copied to clipboard
Using the sidebar for other pages
Hello! Before we start I acknowledge folks are busy, and this might be out of scope for this project. If anything, I want to just document how far I tried to get with this in case someone else searches for info.
Here's a scenario - imagine a more integrated dev docs and developer dashboard type site. We were hoping that instead of running these servers separately to just have 1 domain that takes care of developers on our platform. This means adding things like login/signup and a dashboard. Which means connecting up to graphql endpoint via apollo client of course :).
Most of this works perfectly fine in gatsby, it's a pretty standard setup to create a client and a provider.
That being said there are 4 things I'd like to highlight as problematic.
- The sidebar does not appear for pages that gatsby-theme-apollo-docs does not know about. This is hard to resolve, for now I'm using copy pasta as a workaround and creating the page in my own gatsby-node.js file. Reading through the source code of gatsby-node.js indicates that the sidebar contents are generated and loaded into gql for every page. It doesn't however seem particularly simple to use these functions from dependent packages (unless I'm missing something). I even tried to query for other page's sidebars from my own gatsby-node file, but I don't think the pages are ready to be queried at that time.
- All pages not known to gatsby-theme-apollo-docs don't have a version and therefore the Eyebrow appears, forcing you to hard code a version and versionDifference using gatsby-node's createPage API.
- Relative links don't seem to work in the sidebar I tried
[Dashboard](/dashboard)
and[Dashboard](dashboard)
under a sidebar category and the root. - It would be useful to use typography styles or components that matched the rest of the theme easily on these other pages.
Solutions I'd propose:
- Extract some functions out of gatsby-node.js that can be used to generate sidebars.
- Create a set of functions that aren't super tied to gatsby that can be used to generate a sidebar.
- Don't show the eyebrow for pages that don't have a versionDifference at all.
- Relative links via Markdown should be honored even if they point to internal pages.
Another workaround for all this is to just build absolutely everything in our app in MDX, or at least make that the starting point for each entry, which we don't mind doing. Iterating with this seems to be difficult because changes to gatsby-config.js don't seem to get picked up on save (requiring a full server restart).