docs: codesandbox graphql embeds (#21000)

* add lazy loading and remove explorer from some embeds * add note about contributing graphql examples * Apply suggestions from code review Co-Authored-By: LB <barth.laurie@gmail.com> * Update docs/contributing/docs-contributions.md Co-Authored-By: LB <barth.laurie@gmail.com> * Update docs/contributing/docs-contributions.md Co-authored-by: LB <laurie@gatsbyjs.com> Co-authored-by: GatsbyJS Bot <mathews.kyle+gatsbybot@gmail.com>
gatsbyjs · Jan 30, 2020 · ae6d474 · ae6d474
1 parent 8f11c7d
commit ae6d474
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 22 deletions.
diff --git a/docs/contributing/docs-contributions.md b/docs/contributing/docs-contributions.md
@@ -103,6 +103,22 @@ It can be necessary to change a heading within the docs. It's important to note
 - Determine the URL you're looking for. `Changing headers` is linked with a URL ending in `changing-headers`, `Docs renaming instructions` becomes `docs-renaming-instructions`, etc.
 - Update all instances of the old URL to your new one. [Find and replace](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) in VS Code can help. Check that the context of the original link reference still makes sense with the new one.
 
+## Adding embedded GraphQL examples
+
+There are embedded examples in a few places in the docs (like the [GraphQL Reference guide](/docs/graphql-reference/)) that provide a working version of the code described. In the specific example of the GraphQL Query Options Reference page, these examples of the GraphiQL interface show how data can be queried from Gatsby's data layer.
+
+To write a new GraphQL example, a Codesandbox project with a Gatsby site can be opened at its server container link, for example: [https://711808k40x.sse.codesandbox.io/](https://711808k40x.sse.codesandbox.io/). Because Codesandbox is running a Gatsby site in [`develop` mode instead of `build` mode](/docs/overview-of-the-gatsby-build-process/) you can navigate to GraphiQL by adding `/___graphql` to the link. Write an example query, and when you have a query you are satisfied with, the query fields and names will be saved as URL parameters so you can share the link. Copy the URL and use it as the `src` of an iframe:
+
+```mdx
+Here's an example of a GraphQL query inline:
+
+<iframe src="https://711808k40x.sse.codesandbox.io/___graphql?query=query%20TitleQuery%20%7B%0A%20%20site%20%7B%0A%20%20%20%20siteMetadata%20%7B%0A%20%20%20%20%20%20title%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%0A&explorerIsOpen=false&operationName=TitleQuery" /> // highlight-line
+
+More markdown content...
+```
+
+> Note that you should set the `explorerIsOpen` parameter in the URL to `false` if it isn't already.
+
 ## Docs renaming instructions
 
 Sometimes it makes sense to move or rename a file as part of docs restructuring or for content clarification. While we recommend keeping URLs consistent as often as possible, here are some tips to minimize errors and keep the docs in a good state: