💜 Themes that we use to build Gatsby sites at Apollo
License: MIT License
⚠️ These packages are no longer being maintained. Feel free to continue using them, but we won't be supporting them moving forward.
This repo contains Gatsby themes made by Apollo.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
Reported by @justinanastos
For some reason, the h2/h3 tags are not displaying within the docs article or on the right hand nav.
See https://5c7dc06c86dd760008a87e71--apollo-client-docs.netlify.com/docs/react/essentials/local-state for an example. The docs page should have all the same headings as: https://www.apollographql.com/docs/react/essentials/local-state.html
We should generate custom social sharing cards for each docs page that show the title of the page instead of the generic "Apollo Docs" card we currently have.
Not super high priority, but we should address this soonish.
cc @debergalis
Right now, they're sorted alphabetically. We should weight them so Platform, Client, and Server results (in that order) appear first.
Since this theme uses the experimental fs promises API, it will only run on Node >= 10. We might want to mention this in the README of each of our docs repos, so people understand why they're running into errors like the following, when attempting to start docs locally using say Node 8:
I followed #61 (comment) to test out overshadowing color but it seems something has changed internally over at space-kit that causes a palette check with the new color?
Before launch, our code block should have a footer with:
```lines=4,7 file="src/index.js"
Design reference: https://apollographql.atlassian.net/jira/software/projects/DX/boards/7?selectedIssue=DX-9
https://deploy-preview-355--apollo-docs-index.netlify.com/docs/
^ The Graph layer image at the bottom should display properly
Hi!
Our team is referencing your theme pretty closely for developing our own documentation site. I see this as a means of maybe collaborating on a more abstract package/theme that could store more abstractable components such as the top navigation, side nav, and/or main content window.
Our theme is still in the works and subject to change but figured I would mention and get the ball rolling rather than wait until after the fact. We use our own ukit which is based off of bootstrap 4 and reactstrap.
This is an interesting one.
Summary: Unused (yet essential) imports in TypeScript code blocks are removed in the resulting JavaScript code because they're assumed to be TypeScript types/constructs (types, interfaces, etc).
Check out this GIF for example. The first two lines get nuked.
Exists on live Apollo Docs site as well as theme.
Safari Version 13.0.4 (15608.4.9.1.3)
I would expect the hash at the end of URL intended to scroll to a heading of a page to be case insensitive. It appears to be case sensitive.
Works: https://www.apollographql.com/docs/apollo-server/features/data-sources#http-methods
Does not work: https://www.apollographql.com/docs/apollo-server/features/data-sources#HTTP-Methods
Scrolling around the new docs site, I feel I’m really missing the scroll state being tracked in the nav. I would like for there to be some sort of indicator in the nav showing me which section I’m reading, otherwise I get lost in all the content and my own understanding of where I am on the page.
I use Ghostery for ad blocking. When I open https://www.apollographql.com/support/ in Safari with Ghostery enabled, i get a blank white page.
Currently, the right nav considers "within one half page height away from a heading" as that heading being active. It should really switch when the document is scrolled one half or greater of the distance between the heading and the last heading.
In the code block, the alignment between the line numbers and the code looks a bit off. Ideally, the line numbers and code should be aligned on the bottom of the line instead of the top:
In this page, formatting codes are not being interpreted:
https://www.apollographql.com/docs/react/essentials/mutations/
Actual result: Raw markdown codes visible
Expected(?) result: Formatting similar to the corresponding section of the Queries page
Chrome: Version 75.0.3770.100 (Official Build) (64-bit)
OSX: 10.14.5 (18F132)
Currently, we assume all old versions have YAML configs and not the new Gatsby theme config. This line (https://github.com/apollographql/gatsby-theme-apollo/blob/master/packages/gatsby-theme-apollo-docs/gatsby-node.js#L148) looks for _config.yml, but I need to make it check for gatsby-config.js as well.
[email protected] may have a bug.
Ref: less/less.js#3414
I have a following error.
ERROR in ./node_modules/gatsby-theme-apollo/src/styles.less (./node_modules/css-loader??ref--16-oneOf-1-1!./node_modules/postcss-loader/lib??postcss-3!./node_modules/less-loader/dist/cjs.js??ref--16-oneOf-1-3!./node_modules/gatsby-theme-apollo/src/styles.less)
Module build failed (from ./node_modules/less-loader/dist/cjs.js):
Class constructor FileManager cannot be invoked without 'new'
in undefined (line undefined, column undefined)
@ ./node_modules/gatsby-theme-apollo/src/styles.less 2:14-179 21:1-42:3 22:19-184
@ ./node_modules/gatsby-theme-apollo/src/components/layout.js
@ ./node_modules/gatsby-theme-apollo/index.js
@ ./src/components/template.js
@ ./.cache/sync-requires.js
@ ./.cache/app.js
@ multi ./node_modules/event-source-polyfill/src/eventsource.js (webpack)-hot-middleware/client.js?path=/__webpack_hmr&reload=true&overlay=false ./.cache/app
To avoid this error, I did downgrade less to [email protected] by adding
"resolutions": {
"less": "3.9.0"
},
in my package.json.
Currently, if there is an error in the build, the gatsby build command still seems to exit with a truthy value. This causes Netlify to think that the build was successful, and gives the impression that everything is okay, when it is in-fact going to break the documentation entirely if the PR is merged.
As a concrete example, the error shown on this Netlify deploy from apollographql/apollo-server#2616 (but also reproducible locally below, basically, the file referenced in the config is missing because of human error — i.e. uploads vs upload naming inconsistency):
$ npx gatsby build --prefix-paths
success open and validate gatsby-configs — 0.021 s
success load plugins — 0.207 s
success onPreInit — 0.002 s
success delete html and css files from previous builds — 0.004 s
success initialize cache — 0.007 s
success copy gatsby files — 0.190 s
success onPreBootstrap — 0.016 s
success source and transform nodes — 0.022 s
success building schema — 0.228 s
error Error: Doc not found: docs/source/features/file-uploads.md@HEAD
at getContents (/Users/jesse/Dev/apollo/apollo-platform-devkit/packages/apollo-server/docs/node_modules/gatsby-theme-apollo-docs/gatsby-node.js:151:21)
at Promise.all.sidebarItems.map (/Users/jesse/Dev/apollo/apollo-platform-devkit/packages/apollo-server/docs/node_modules/gatsby-theme-apollo-docs/gatsby-node.js:64:28)
at Array.map (<anonymous>)
at getContents (/Users/jesse/Dev/apollo/apollo-platform-devkit/packages/apollo-server/docs/node_modules/gatsby-theme-apollo-docs/gatsby-node.js:52:20)
at <anonymous>
at process._tickCallback (internal/process/next_tick.js:189:7)
success createPages — 2.395 s
success createPagesStatefully — 0.028 s
success onPreExtractQueries — 0.000 s
success update schema — 0.101 s
success extract queries from components — 0.162 s
success run static queries — 0.021 s — 3/3 148.13 queries/second
success run page queries — 0.058 s — 16/16 279.38 queries/second
success write out page data — 0.008 s
success write out redirect data — 0.001 s
success onPostBootstrap — 0.003 s
info bootstrap finished - 7.706 s
error (node:55501) DeprecationWarning: Tapable.plugin is deprecated. Use new API on `.hooks` instead
error (node:55501) DeprecationWarning: Resolver#doResolve: The type arguments (string) is now a hook argument (Hook). Pass a reference to the hook instead.
success Building production JavaScript and CSS bundles — 23.555 s
success Building static HTML for pages — 4.251 s — 16/16 14.08 pages/second
info Done building in 35.521 secIs there a way to make that error more catastrophic and have the build immediately exit with a non-zero error code (i.e. process.exit(1))? That should cause the Netlify preview deploy status to not be green ✅ and give us the heads-up we need to avoid breaking documentation ❌.
I'm probably missing something here but it doesn't look like react or react-dom is included as a dependency here and its magically working.
I was noticing this on my project and figured I would open an issue here as well.
The font size for inline code highlighting looks too small compared with the rest of the body text.
In this screenshot, you can see that the font size for the inline code highlighted text is the same, regardless of whether the body text is smaller or larger. Ideally, the font size for inline code highlighting should scale with the body text:
Lmk if this is confusing, I'm not sure if I'm explaining this well 🤦♀️
Currently on the Apollo Client docs, we have version switching available between versions 2.5 and 2.4. I'm not seeing any version switching available for the client docs PR:
https://5c7dc06c86dd760008a87e71--apollo-client-docs.netlify.com/docs/react/
Hi,
following the documentation under https://apollographql.com/client, I've found a link unavailable (https://github.com/apollographql/apollo-client/blob/master/src/src/ApolloClient.ts#L75 will produce a 404 error).
I've attached an image to show where is located the problem.
The problem is the word "src" repeated 2 times in the url.
Currently, links are underlined by default and the underline disappears on hover. We should switch this behavior so links are not underlined by default and the underline only appears on hover. This is more consistent with UX patterns that you typically see on the web.
When I scroll the page, I want the right hand nav (Is this section) to stay fixed where it is while the header and line divider scroll off the page. Something about scrolling the right hand nav up all the way up to the top navbar feels a bit distracting and takes my eye off the content.
Maybe it just needs more margin between the top navbar and the right hand nav?
In the design, "In this section" should be bold. Currently, it's not appearing as bold.
Hi, The use of the experimental themes by apollo docs is very cool.
I am not sure if the team intends to make these themes reusable outside of Apollo, but that would be very useful. If not, then please close the issue.
I had a quick attempt to reuse them and got quite far, but noticed these issues:
Shadowing doesn't seem to work because it seems like the gatsby theme framework assumes that the project source folder is src. Renaming it to src caused the apollo themes to not work, so I created a symbolic link and it works. This is probably a problem better fixed in the gatsby themes framework
There are a number of components (search, logo, title, github, spectrum, navConfig, sidebarlink, etc) that would be nice if they were externally configurable, because shadowing them results in almost shadowing everything.
https://www.apollographql.com/docs/resources/graphql-glossary
1 goal : have automated checkers use the same url as an editor would see
A link checker: https://www.drlinkcheck.com/account/subscriptions/1/projects/2/reports/broken?offset=1753&count=100
The main header seems to be scrolling off the page in safari. Might need to make this fixed position instead of sticky.
Video: https://cl.ly/e28eab7f4c37
I could not capture this with a screen capture.
I navigated to https://www.apollographql.com/docs/platform/schema-validation#setup and see the page flickering when scrolling. To be more specific, it appears as though this image is appearing and disappearing after I release the mouse and the browser continues it's inertial scrolling.
Mac OS 10.14.3 (I did not install the March 25th, 2019 update). Safari 12.0.3.
Hovering over an h2/h3 and clicking should link you to its anchor tag (https://www.apollographql.com/docs/apollo-server/features/errors.html - we even have a link icon appear next to the text). Currently, the only way for me to access the anchor tag is to click the heading in the right hand nav. A user should also be able to click on the heading itself to link to its anchor tag.
See https://deploy-preview-2394--apollo-server-docs.netlify.com/docs/apollo-server/features/errors for an example.
This could be caused if we’re displaying the docs content in a scrollable div instead of in a doc that grows.
This is what AMP does and its frustrating.
Given that I'm on a long docs page and I scroll past the top, I can see the sections of the current page and they highlight as I scroll. This is awesome. However, I don't know what section I'm currently in. Maybe we could replace the In this section text with the current section name?
For the Apollo Client docs, we use TSDoc to automatically generate API docs. Currently, they're not showing up in the Client docs: https://5c7dc06c86dd760008a87e71--apollo-client-docs.netlify.com/docs/react/api/apollo-client
It's a nitpick, but it would be really nice if there was a drawer transition for the drawers in the nav bar.
The selector for the main heading needs to be updated to account for the style changes.
https://github.com/algolia/docsearch-configs/blob/master/configs/apollodata.json#L24
Right now all of the docs are showing as Documentation as the main heading. If this was intended you can close. I wanted to open the issue here so that you guys at least get the notification.
If it is an issue I can create a PR on their github repo to fix it but not sure if they will accept as I am not a contributor/member of this org.
I like the cleanliness of having the left nav be closed to sub-headers, but I'm wondering if there's a nice looking way to get an expand/collapse all button in there. When trying to find some obscure sub-document it's helpful to be able to see the full table of contents easily.
When navigating, the left nav closes whenever navigating on the page. This leads to an annoying experience, where I have trouble remembering what I was trying to look at/which overall section it's stored in.
My impression is that this can be solved with localStorage or maybe even link-state 🤔
Hi,
I'm trying to use this theme for one of my own projects.
I'm in the process of branding the theme to fit more towards our own visual appearance. I've installed the v2 of gatsby-theme-apollo-docs and managed to change the logo via component shadowing, but now I'm a bit stuck with colors. What is the intended way of tweaking the colors? Is there a way to assign something like a primary color, so it's applied throughout the theme?
Cheers
https://deploy-preview-2394--apollo-server-docs.netlify.com/docs/apollo-server/features/errors#default-information is displaying a broken image in the default information section with the alt text "Screenshot demonstrating an error stacktrace and additional"
James reported this in #team-dx today. I remember inertial scrolling was an issue with the Principled GraphQL launch - let's check to make sure the fix was implemented here too.
It looks like a fair amount of the docs content isn't being indexed / made searchable by Algolia:
Clicking different articles in the left nav bar resets the scroll position of the nav every time you click to a new article. This leads to a "jumpy" feeling if you're just trying to browse through different articles and you end up needing to re-scroll to the position you were at before.
It would be really nice if we could maintain this scroll position. The https://gatsbyjs.org/docs/ site does it, so it seems like it should be feasible in Gatsby themes :)
Summary: I'm using MultiCodeBlock to present TypeScript code blocks but when I use TypeScript Generics, the styling breaks from that line until the end of the code block.
Here's an example:
Given this block:
_src/index.tsx_
<MultiCodeBlock>
```tsx
import { ApolloClient } from 'apollo-client';
import { InMemoryCache, NormalizedCacheObject } from 'apollo-cache-inmemory';
import { HttpLink } from 'apollo-link-http';
const cache: ApolloClient<NormalizedCacheObject> = new InMemoryCache();
const link = new HttpLink({
uri: 'http://localhost:4000/'
});
const client = new ApolloClient({
cache,
link
});We might see:
I suspect it has something to do with being interpreted as JSX or an HTML element.
Watch what happens when I add a closing tag to NormalizedCacheObject.
Though the code is syntactically incorrect, the rest of the styles in the code block can be applied.
Any ideas on this one?
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.