Skip to content

aschaeffer/mdbook-preprocessor-graphql-playground

Repository files navigation

GraphQL Playground for your mdbook

A preprocessor for mdbook to add a GraphQL playground.


Crate downloads


preview

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