mdbook-preprocessor-graphql-playground

A preprocessor for mdbook to add GraphQL playgrounds.

Demo

https://aschaeffer.github.io/mdbook-preprocessor-graphql-playground/

Usage

1. Install mdbook-preprocessor-graphql-playground

   cargo install mdbook-preprocessor-graphql-playground
   

2. Add to book.toml:

   [preprocessor.graphql-playground]
   command = "mdbook-graphql-playground"
   renderer = ["html"]
   
   [output]
   
   [output.html]
   additional-js = ["graphql-playground-react-middleware.js", "graphql-playground.js"]
   additional-css = ["graphql-playground.css"]
   

3. Copy assets into the book root directory:

   cp assets/graphql-playground.css <book_dir>
   cp assets/graphql-playground.js <book_dir>
   cp assets/graphql-playground-react-middleware.js <book_dir>
   cp assets/images/* <book_dir>/src/images/
   

4. Create a query file

   mkdir -p <book_dir>/queries/swapi
   nano <book_dir>/queries/swapi/all-planets.query.graphql
   

5. Create a config file

   mkdir <book_dir>/configs
   nano <book_dir>/configs/swapi.json
   

6. Embed the GraphQL Playground in your markdown files

   {{ graphql_playground(config="/configs/swapi.json") }}
   

Query files

• You can have multiple queries

query AllPlanetsQuery {
  allPlanets {
    planets {
      name
      diameter
    }
  }
}

Config files

• You can have multiple config files
• You can have multiple tabs, each refers to a query

{
  "title": "The Star Wars API",
  "description": "Explore the star wars API using mdbook-preprocessor-graphql-playground",
  "endpoint": "https://swapi-graphql.netlify.app/.netlify/functions/index",
  "tabs": [
    {
      "name": "All Planets",
      "url": "/queries/swapi/all-planets.query.graphql"
    }
  ]
}

Use a config in the book

1. Embed with the graphql_playground function
2. Specify the location of the config file with the config parameter

{{ graphql_playground(config="/configs/swapi.json") }}

Example

A full example can be found in this repository