From ab22c065a818eae1412e218e213aec9f79f10a87 Mon Sep 17 00:00:00 2001
From: Ben Fradet <benjamin.fradet@gmail.com>
Date: Mon, 16 Mar 2020 15:19:16 +0100
Subject: [PATCH] Update documentation due to the new http4s client requirement

---
 docs/docs/activity.md     |  32 ++++----
 docs/docs/auth.md         |  34 +++++---
 docs/docs/contributing.md |  19 +++--
 docs/docs/docs.md         | 169 +++++++++++++++++++++++---------------
 docs/docs/gist.md         |  31 ++++---
 docs/docs/git_data.md     |  42 ++++++----
 docs/docs/issue.md        |  54 ++++++------
 docs/docs/organization.md |  28 ++++---
 docs/docs/project.md      |  37 +++++----
 docs/docs/pull_request.md |  37 +++++----
 docs/docs/repository.md   |  55 ++++++-------
 docs/docs/team.md         |  26 +++---
 docs/docs/user.md         |  32 +++++---
 13 files changed, 347 insertions(+), 249 deletions(-)

diff --git a/docs/docs/activity.md b/docs/docs/activity.md
index b6f9aeb66..065262213 100644
--- a/docs/docs/activity.md
+++ b/docs/docs/activity.md
@@ -15,23 +15,27 @@ with Github4s, you can interact with:
   - [List stargazers](#list-stargazers)
   - [List starred repositories](#list-starred-repositories)
 
-The following examples use `cats.effect.IO` and assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
-import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
-
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import java.util.concurrent._
 
+import cats.effect.{Blocker, ContextShift, IO}
+import github4s.Github
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+import scala.concurrent.ExecutionContext.global
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Notifications
 
@@ -48,7 +52,7 @@ You can subscribe or unsubscribe using `setThreadSub`; it takes as arguments:
 - `ignored`: Determines if all notifications should be blocked from this thread.
 
 ```scala mdoc:compile-only
-val threadSub = Github[IO](accessToken).activities.setThreadSub(5, true, false)
+val threadSub = gh.activities.setThreadSub(5, true, false)
 val response = threadSub.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -73,7 +77,7 @@ You can list the users starring a specific repository with `listStargazers`; it
 To list the stargazers of 47degrees/github4s:
 
 ```scala mdoc:compile-only
-val listStargazers = Github[IO](accessToken).activities.listStargazers("47degrees", "github4s", true)
+val listStargazers = gh.activities.listStargazers("47degrees", "github4s", true)
 val response = listStargazers.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -101,7 +105,7 @@ the repo was last pushed to), optional.
 To list the starred repositories for user `rafaparadela`:
 
 ```scala mdoc:compile-only
-val listStarredRepositories = Github[IO](accessToken).activities.listStarredRepositories("rafaparadela", true)
+val listStarredRepositories = gh.activities.listStarredRepositories("rafaparadela", true)
 val response = listStarredRepositories.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/auth.md b/docs/docs/auth.md
index 6f53b6ca9..a20443d28 100644
--- a/docs/docs/auth.md
+++ b/docs/docs/auth.md
@@ -13,22 +13,29 @@ with Github4s, you can:
 - [Authorize a url](#authorize-a-url)
 - [Get an access token](#get-an-access-token)
 
-The following examples assume the following imports:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-```
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+import scala.concurrent.ExecutionContext.global
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
+
+val gh = Github[IO](httpClient, None)
+```
 
-**NOTE**: In the examples you will see `Github(None)`
-because if you are authenticating for the first time you don't have any access token yet.
+**NOTE**: Above you can see `Github(httpClient, None)`. This is due to the fact that if you are
+authenticating for the first time you don't have any access token yet.
 
 ### Create a new authorization token
 
@@ -43,7 +50,7 @@ You can create a new authorization token using `newAuth`; it takes as arguments:
 - `client_secret`: the 40 character OAuth app client secret for which to create the token.
 
 ```scala mdoc:compile-only
-val newAuth = Github[IO](None).auth.newAuth(
+val newAuth = gh.auth.newAuth(
   "rafaparadela",
   "invalidPassword",
   List("public_repo"),
@@ -73,7 +80,7 @@ You can authorize a url using `authorizeUrl`; it takes as arguments:
 - `scopes`: attached to the token, for more information see [the scopes doc](https://developer.github.com/v3/oauth/#scopes).
 
 ```scala mdoc:compile-only
-val authorizeUrl = Github[IO](None).auth.authorizeUrl(
+val authorizeUrl = gh.auth.authorizeUrl(
   "e8e39175648c9db8c280",
   "http://localhost:9000/_oauth-callback",
   List("public_repo"))
@@ -102,7 +109,7 @@ You can get an access token using `getAccessToken`; it takes as arguments:
 - `state`: the unguessable random string you optionally provided in [Create a new authorization token](#create-a-new-authorization-token).
 
 ```scala mdoc:compile-only
-val getAccessToken = Github[IO](None).auth.getAccessToken(
+val getAccessToken = gh.auth.getAccessToken(
   "e8e39175648c9db8c280",
   "1234567890",
   "code",
@@ -124,3 +131,4 @@ As you can see, a few features of the authorization endpoint are missing.
 As a result, if you'd like to see a feature supported, feel free to create an issue and/or a pull request!
 
 [auth-scala]: https://github.com/47degrees/github4s/blob/master/github4s/src/main/scala/github4s/domain/Authorization.scala
+[http4s-client]: https://http4s.org/v0.21/client/
diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
index 26b251b30..921eb01fc 100644
--- a/docs/docs/contributing.md
+++ b/docs/docs/contributing.md
@@ -139,9 +139,10 @@ we'll be writing our tests in [GHReposSpec][repos-integ-spec]:
 
 ```scala
 "Repos >> ListStatus" should "return a non empty list when a valid ref is provided" taggedAs Integration in {
-    val response = Github[IO](accessToken).repos
-      .listStatuses(validRepoOwner, validRepoName, validCommitSha, headers = headerUserAgent)
-      .unsafeRunSync()
+    val response = client.use { client =>
+      Github[IO](client, accessToken).repos
+        .listStatuses(validRepoOwner, validRepoName, validCommitSha, headers = headerUserAgent)
+    }.unsafeRunSync()
 
     testIsRight[List[Status]](response, { r =>
       r.nonEmpty shouldBe true
@@ -150,9 +151,11 @@ we'll be writing our tests in [GHReposSpec][repos-integ-spec]:
   }
 
   it should "return an error when an invalid ref is provided" taggedAs Integration in {
-    val response = Github[IO](accessToken).repos
-      .listStatuses(validRepoOwner, validRepoName, invalidRef, headers = headerUserAgent)
-      .unsafeRunSync()
+    val response = client.use { client =>
+      Github[IO](client, accessToken).repos
+        .listStatuses(validRepoOwner, validRepoName, invalidRef, headers = headerUserAgent)
+    }.unsafeRunSync()
+
     testIsLeft(response)
     response.statusCode shouldBe notFoundStatusCode
   }
@@ -208,9 +211,7 @@ You can also list statuses through `listStatuses`; it take as arguments:
 To list the statuses for a specific ref:
 
 {triple backtick}scala mdoc:silent
-val listStatuses =
-  Github[IO](accessToken).repos.listStatuses("47degrees", "github4s", "heads/master")
-
+val listStatuses = gh.repos.listStatuses("47degrees", "github4s", "heads/master")
 val response = listStatuses.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/docs.md b/docs/docs/docs.md
index cb67cdf93..89fc02c5e 100755
--- a/docs/docs/docs.md
+++ b/docs/docs/docs.md
@@ -13,21 +13,9 @@ appropriate scopes (i.e. if you want to create gists, your token will need to ha
 
 ## Github4s
 
-First things first, we'll need to import `github4s.Github` which is the entry point to the Github
-API in Github4s.
-
-```scala mdoc:silent
-import github4s.Github
-```
-```scala mdoc:invisible
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
-
-In order for Github4s to work, you'll need an appropriate implicit `ExecutionContext` in Scope.
-
 Github4s uses [Tagless Final encoding](https://typelevel.org/blog/2017/12/27/optimizing-final-tagless.html).
 
-Every Github4s API call returns an `F[GHResponse[A]]` where `F` has an instance of [cats.effect.ConcurrentEffect][cats-concurrent-effect].
+Every Github4s API call returns an `F[GHResponse[A]]` where `F` has an instance of [cats.effect.Sync][cats-sync].
 
 `GHResponse[A]` contains the result `A` given by Github (or an error) as well as the status code and
 headers of the response:
@@ -40,26 +28,60 @@ final case class GHResponse[A](
 )
 ```
 
+To make HTTP calls, Github4s relies on [an http4s' HTTP client][http4s-client] which needs to be
+supplied as we'll see later. Here, we are making use of `JavaNetClientBuilder` because of its ease
+of use in a REPL. However, for production use you should prefer `BlazeClientBuilder` over it as
+detailed in [the documentation][http4s-client].
+
+```scala mdoc:silent
+import java.util.concurrent.Executors
+
+import cats.effect.{Blocker, ContextShift, IO}
+import org.http4s.client.{Client, JavaNetClientBuilder}
+
+import scala.concurrent.ExecutionContext.global
+
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
+```
+
 As an introductory example, we can get a user with the following:
 
-```scala mdoc:silent:fail
-val user1 = Github[IO](accessToken).users.get("rafaparadela")
+```scala mdoc:silent
+import github4s.Github
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val user1 = Github[IO](httpClient, accessToken).users.get("rafaparadela")
 ```
 
 `user1` in this case is a `IO[GHResponse[User]]`.
 
-### Using `F[_]: cats.effect.ConcurrentEffect`
+### Using `F[_]: cats.effect.Sync`
+
+Any type with a `cats.effect.Sync` instance can be used with this example, such as
+`monix.eval.Task`.
 
 ```scala mdoc:compile-only
 object ProgramF {
-  import cats.effect.ConcurrentEffect
-  import scala.concurrent.ExecutionContext
+  import java.util.concurrent.Executors
+
+  import cats.effect.{Blocker, Async}
   import github4s.Github
   import github4s.GithubResponses.GHResponse
   import github4s.domain.User
+  import org.http4s.client.{Client, JavaNetClientBuilder}
+
+  def httpClient[F[_]: Async: ContextShift]: Client[F] = {
+    val blockingPool = Executors.newFixedThreadPool(5)
+    val blocker = Blocker.liftExecutorService(blockingPool)
+    JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+  }
 
-  def u1[F[_]: ConcurrentEffect](implicit ec: ExecutionContext): F[GHResponse[User]] =
-    Github[F](accessToken).users.get("juanpedromoreno")
+  def u1[F[_]: Async: ContextShift]: F[GHResponse[User]] =
+    Github[F](httpClient, accessToken).users.get("juanpedromoreno")
 }
 ```
 
@@ -67,76 +89,78 @@ object ProgramF {
 
 ```scala mdoc:compile-only
 object ProgramIO {
-  import cats.effect.IO
-  import cats.effect.IO.contextShift
-  import scala.concurrent.ExecutionContext.Implicits.global
-  import github4s.Github
+  import java.util.concurrent.Executors
 
-  implicit val IOContextShift = IO.contextShift(global)
-
-  val u1 = Github[IO](accessToken).users.get("juanpedromoreno")
-  u1.unsafeRunSync()
-}
-```
-
-### Using `monix.eval.Task`
-
-```scala mdoc:silent:fail
-object ProgramTask {
-    import monix.execution.Scheduler.Implicits.global
-    import monix.eval.Task
-    import github4s.Github
-
-    val u2 = Github[Task](accessToken).users.get("rafaparadela")
-}
-```
+  import cats.effect.{Blocker, ContextShift, IO}
+  import github4s.Github
+  import org.http4s.client.{Client, JavaNetClientBuilder}
 
-As mentioned above, `u2` should be a `Task[GHResponse[User]]`
+  import scala.concurrent.ExecutionContext.global
 
-```scala mdoc:silent:fail
-import github4s.GithubResponses.GHResult
+  val httpClient: Client[IO] = {
+    val blockingPool = Executors.newFixedThreadPool(5)
+    val blocker = Blocker.liftExecutorService(blockingPool)
+    implicit val cs: ContextShift[IO] = IO.contextShift(global)
+    JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+  }
 
-ProgramTask.u2.runAsync() {
-  case GHResult(Right(result), status@_, headers@_) => doSomething
-  case GHResult(Left(error), status@_, headers@_) => doSomethingElse
+  val u2 = Github[IO](httpClient, accessToken).users.get("juanpedromoreno")
+  u2.unsafeRunSync()
 }
-
 ```
 
-Support for `cats.Id` and `Future` are provided with `GithubIOSyntax` which contains syntax to lift from `IO`.
-
 ### Using `cats.Id`
 
+Support for `cats.Id` is provided with `GithubIOSyntax` which contains syntax to lift from `IO`.
+
 ```scala mdoc:compile-only
 object ProgramId {
-  import cats.effect.IO
-  import cats.effect.IO.contextShift
-  import scala.concurrent.ExecutionContext.Implicits.global
+  import java.util.concurrent.Executors
+
+  import cats.effect.{Blocker, ContextShift, IO}
   import github4s.Github
   import github4s.GithubIOSyntax._
+  import org.http4s.client.{Client, JavaNetClientBuilder}
+
+  import scala.concurrent.ExecutionContext.global
 
-  implicit val IOContextShift = IO.contextShift(global)
+  val httpClient: Client[IO] = {
+    val blockingPool = Executors.newFixedThreadPool(5)
+    val blocker = Blocker.liftExecutorService(blockingPool)
+    implicit val cs: ContextShift[IO] = IO.contextShift(global)
+    JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+  }
 
-  val u3 = Github[IO](accessToken).users.get("rafaparadela").toId
+  val u4 = Github[IO](httpClient, accessToken).users.get("juanpedromoreno").toId
 }
 ```
 
 ### Using `Future`
 
+Support for `Future` is provided with `GithubIOSyntax` which contains syntax to lift from `IO`.
+
 ```scala mdoc:compile-only
 object ProgramFuture {
-  import cats.effect.IO
-  import cats.effect.IO.contextShift
-  import scala.concurrent.ExecutionContext.Implicits.global
-  import scala.concurrent.duration._
-  import scala.concurrent.Await
+  import java.util.concurrent.Executors
+
+  import cats.effect.{Blocker, ContextShift, IO}
   import github4s.Github
   import github4s.GithubIOSyntax._
+  import org.http4s.client.{Client, JavaNetClientBuilder}
 
-  implicit val IOContextShift = IO.contextShift(global)
+  import scala.concurrent.Await
+  import scala.concurrent.ExecutionContext.Implicits.global
+  import scala.concurrent.duration._
+
+  val httpClient: Client[IO] = {
+    val blockingPool = Executors.newFixedThreadPool(5)
+    val blocker = Blocker.liftExecutorService(blockingPool)
+    implicit val cs: ContextShift[IO] = IO.contextShift(global)
+    JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+  }
 
-  val u4 = Github[IO](accessToken).users.get("dialelo").toFuture
-  Await.result(u4, 2.seconds)
+  val u5 = Github[IO](httpClient, accessToken).users.get("juanpedromoreno").toFuture
+  Await.result(u5, 2.seconds)
 }
 ```
 
@@ -147,15 +171,26 @@ Headers are an optional field for any Github API request:
 
 ```scala mdoc:silent:fail
 object ProgramEvalWithHeaders {
+  import java.util.concurrent.Executors
+
+  import cats.effect.Blocker
+  import github4s.Github
   import monix.execution.Scheduler.Implicits.global
   import monix.eval.Task
-  import github4s.Github
+  import org.http4s.client.{Client, JavaNetClientBuilder}
+
+  val httpClient: Client[Task] = {
+    val blockingPool = Executors.newFixedThreadPool(5)
+    val blocker = Blocker.liftExecutorService(blockingPool)
+    JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+  }
 
   val userHeaders = Map("user-agent" -> "github4s")
-  val u5 = Github[Task](accessToken).users.get("rafaparadela", userHeaders)
+  val u6 = Github[Task](accessToken).users.get("rafaparadela", userHeaders)
 }
 ```
 
 [access-token]: https://github.com/settings/tokens
-[cats-concurrent-effect]: https://typelevel.org/cats-effect/typeclasses/concurrent-effect.html
+[cats-sync]: https://typelevel.org/cats-effect/typeclasses/sync.html
 [monix-task]: https://monix.io/docs/3x/eval/task.html
+[http4s-client]: https://http4s.org/v0.21/client/
diff --git a/docs/docs/gist.md b/docs/docs/gist.md
index 442250587..5780938c2 100644
--- a/docs/docs/gist.md
+++ b/docs/docs/gist.md
@@ -13,20 +13,27 @@ with Github4s, you can:
 - [Get a single gist or specific revision of a gist](#get-a-single-gist-or-specific-revision-of-a-gist)
 - [Edit a gist](#edit-a-gist)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
+
+import scala.concurrent.ExecutionContext.global
+
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-implicit val IOContextShift = IO.contextShift(global)
 val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
 ```
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
-
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
 
 ## Create a gist
 
@@ -45,7 +52,7 @@ val gistfiles = Map(
   "token.scala" -> GistFile("val accessToken = sys.env.get(\"GITHUB4S_ACCESS_TOKEN\")"),
   "gh4s.scala"  -> GistFile("val gh = Github(accessToken)")
 )
-val newGist = Github[IO](accessToken).gists.newGist("Github4s entry point", public = true, gistfiles)
+val newGist = gh.gists.newGist("Github4s entry point", public = true, gistfiles)
 val response = newGist.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -67,7 +74,7 @@ You can create a gist using `getGist`; it takes as arguments:
 To get a single gist:
 
 ```scala mdoc:compile-only
-val singleGist = Github[IO](accessToken).gists.getGist("aa5a315d61ae9438b18d")
+val singleGist = gh.gists.getGist("aa5a315d61ae9438b18d")
 val response = singleGist.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -78,7 +85,7 @@ response.result match {
 Similarly, to get a specific revision of a gist:
 
 ```scala mdoc:compile-only
-val sepcificRevisionGist = Github[IO](accessToken).gists.getGist("aa5a315d61ae9438b18d", Some("4e481528046a016fc11d6e7d8d623b55ea11e372"))
+val sepcificRevisionGist = gh.gists.getGist("aa5a315d61ae9438b18d", Some("4e481528046a016fc11d6e7d8d623b55ea11e372"))
 val response = sepcificRevisionGist.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -109,7 +116,7 @@ val editfiles = Map(
   "token.class"  -> None
 )
 
-val updatedGist = Github[IO](accessToken).gists.editGist("aa5a315d61ae9438b18d", "Updated github4s entry point", editfiles)
+val updatedGist = gh.gists.editGist("aa5a315d61ae9438b18d", "Updated github4s entry point", editfiles)
 val response = updatedGist.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/git_data.md b/docs/docs/git_data.md
index 3cd6f0723..0fa9c0472 100644
--- a/docs/docs/git_data.md
+++ b/docs/docs/git_data.md
@@ -22,21 +22,27 @@ with Github4s, you can:
 For more information on the Git object database,
 please read the [Git Internals](https://git-scm.com/book/en/v1/Git-Internals) chapter of the Pro Git book.
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Git Data
 
@@ -57,7 +63,7 @@ You can get a reference using `getReference`, it takes as arguments:
 - `ref`: ref formatted as `heads/branch`.
 
 ```scala mdoc:compile-only
-val getReference = Github[IO](accessToken).gitData.getReference("47degrees", "github4s", "heads/master")
+val getReference = gh.gitData.getReference("47degrees", "github4s", "heads/master")
 val response = getReference.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -83,7 +89,7 @@ If it doesn't start with 'refs' and has at least two slashes, it will be rejecte
 - `sha`: the SHA1 value to set this reference.
 
 ```scala mdoc:compile-only
-val createReference = Github[IO](accessToken).gitData.createReference(
+val createReference = gh.gitData.createReference(
   "47deg",
   "github4s",
   "refs/heads/master",
@@ -111,7 +117,7 @@ You can update a reference using `updateReference`; it takes as arguments:
 Setting it to `false` will make sure you're not overwriting work. Default: `false`.
 
 ```scala mdoc:compile-only
-val updateReference = Github[IO](accessToken).gitData.updateReference(
+val updateReference = gh.gitData.updateReference(
   "47deg",
   "github4s",
   "heads/master",
@@ -138,7 +144,7 @@ You can get a commit using `getCommit`; it takes as arguments:
 - `sha`: the sha of the commit.
 
 ```scala mdoc:compile-only
-val getCommit = Github[IO](accessToken).gitData.getCommit("47degrees", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891")
+val getCommit = gh.gitData.getCommit("47degrees", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891")
 val response = getCommit.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -164,7 +170,7 @@ for a merge commit, an array of more than one should be provided.
 - `author`: object containing information about the author.
 
 ```scala mdoc:compile-only
-val createCommit = Github[IO](accessToken).gitData.createCommit(
+val createCommit = gh.gitData.createCommit(
   "47deg",
   "github4s",
   "New access token",
@@ -193,7 +199,7 @@ You can create a blob using `createBlob`; it takes as arguments:
 - `encoding`: the encoding used for content. Currently, "utf-8" and "base64" are supported. Default: "utf-8".
 
 ```scala mdoc:compile-only
-val createBlob = Github[IO](accessToken).gitData.createBlob("47degrees", "github4s", "New access token", Some("utf-8"))
+val createBlob = gh.gitData.createBlob("47degrees", "github4s", "New access token", Some("utf-8"))
 val response = createBlob.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -224,7 +230,7 @@ You can get a tree using `getTree`; it takes as arguments:
 - `recursive`: flag whether to get the tree recursively.
 
 ```scala mdoc:compile-only
-val getTree = Github[IO](accessToken).gitData.getTree("47degrees", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891", true)
+val getTree = gh.gitData.getTree("47degrees", "github4s", "d3b048c1f500ee5450e5d7b3d1921ed3e7645891", true)
 val response = getTree.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -261,7 +267,7 @@ You can create a tree using `createTree`; it takes as arguments:
 
 ```scala mdoc:compile-only
 import github4s.domain.TreeDataSha
-val createTree = Github[IO](accessToken).gitData.createTree(
+val createTree = gh.gitData.createTree(
   "47deg",
   "github4s",
   Some("827efc6d56897b048c772eb4087f854f46256132"),
@@ -297,7 +303,7 @@ Normally this is a `commit`, but it can also be a `tree` or a `blob`.
 
 ```scala mdoc:compile-only
 import github4s.domain.RefAuthor
-val createTag = Github[IO](accessToken).gitData.createTag(
+val createTag = gh.gitData.createTag(
   "47deg",
   "github4s",
   "v0.1.1",
diff --git a/docs/docs/issue.md b/docs/docs/issue.md
index a33227f29..407c7a447 100644
--- a/docs/docs/issue.md
+++ b/docs/docs/issue.md
@@ -30,21 +30,27 @@ with Github4s, you can interact with:
 - [Milestones](#milestones)
   - [List milestones for a respository](#list-milestones-for-a-repository)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Issues
 
@@ -61,7 +67,7 @@ To create an issue:
 
 ```scala mdoc:compile-only
 val createIssue =
-  Github[IO](accessToken).issues.createIssue("47degrees", "github4s", "Github4s", "is awesome", None, List("Label"), List("Assignee"))
+  gh.issues.createIssue("47degrees", "github4s", "Github4s", "is awesome", None, List("Label"), List("Assignee"))
 val response = createIssue.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -89,7 +95,7 @@ To edit an issue:
 
 ```scala mdoc:compile-only
 val editIssue =
-  Github[IO](accessToken).issues.editIssue("47degrees", "github4s", 1, "open", "Github4s", "is still awesome", None, List("Label"), List("Assignee"))
+  gh.issues.editIssue("47degrees", "github4s", 1, "open", "Github4s", "is still awesome", None, List("Label"), List("Assignee"))
 val response = editIssue.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -111,7 +117,7 @@ You can also list issues for a repository through `listIssues`; it takes as argu
 To list the issues for a repository:
 
 ```scala mdoc:compile-only
-val listIssues = Github[IO](accessToken).issues.listIssues("47degrees", "github4s")
+val listIssues = gh.issues.listIssues("47degrees", "github4s")
 val response = listIssues.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -135,7 +141,7 @@ You can also get a single issue of a repository through `getIssue`; it takes as
 To get a single issue from a repository:
 
 ```scala mdoc:compile-only
-val issue = Github[IO](accessToken).issues.getIssue("47degrees", "github4s", 17)
+val issue = gh.issues.getIssue("47degrees", "github4s", 17)
 val response = issue.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -167,7 +173,7 @@ val searchParams = List(
   IssueTypeIssue,
   SearchIn(Set(SearchInTitle))
 )
-val searchIssues = Github[IO](accessToken).issues.searchIssues("existential", searchParams)
+val searchIssues = gh.issues.searchIssues("existential", searchParams)
 val response = searchIssues.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -191,7 +197,7 @@ You can list comments of an issue with the following parameters:
  To list comments:
 
 ```scala mdoc:compile-only
-val commentList = Github[IO](accessToken).issues.listComments("47degrees", "github4s", 17)
+val commentList = gh.issues.listComments("47degrees", "github4s", 17)
 val response = commentList.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -214,7 +220,7 @@ You can create a comment for an issue with the following parameters:
  To create a comment:
 
 ```scala mdoc:compile-only
-val createcomment = Github[IO](accessToken).issues.createComment("47degrees", "github4s", 17, "this is the comment")
+val createcomment = gh.issues.createComment("47degrees", "github4s", 17, "this is the comment")
 val response = createcomment.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -238,7 +244,7 @@ You can edit a comment from an issue with the following parameters:
  To edit a comment:
 
 ```scala mdoc:compile-only
-val editComment = Github[IO](accessToken).issues.editComment("47degrees", "github4s", 20, "this is the new comment")
+val editComment = gh.issues.editComment("47degrees", "github4s", 20, "this is the new comment")
 val response = editComment.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -261,7 +267,7 @@ You can delete a comment from an issue with the following parameters:
  To delete a comment:
 
 ```scala mdoc:compile-only
-val deleteComment = Github[IO](accessToken).issues.deleteComment("47degrees", "github4s", 20)
+val deleteComment = gh.issues.deleteComment("47degrees", "github4s", 20)
 val response = deleteComment.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -285,7 +291,7 @@ You can list labels for an issue with the following parameters:
  To list labels:
 
 ```scala mdoc:compile-only
-val labelListRepository = Github[IO](accessToken).issues.listLabelsRepository("47degrees", "github4s")
+val labelListRepository = gh.issues.listLabelsRepository("47degrees", "github4s")
 val response = labelListRepository.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -308,7 +314,7 @@ You can list labels for an issue with the following parameters:
  To list labels:
 
 ```scala mdoc:compile-only
-val labelList = Github[IO](accessToken).issues.listLabels("47degrees", "github4s", 17)
+val labelList = gh.issues.listLabels("47degrees", "github4s", 17)
 val response = labelList.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -331,7 +337,7 @@ You can add existing labels to an issue with the following parameters:
  To add existing labels to an issue:
 
 ```scala mdoc:compile-only
-val assignedLabelList = Github[IO](accessToken).issues.addLabels("47degrees", "github4s", 17, List("bug", "code review"))
+val assignedLabelList = gh.issues.addLabels("47degrees", "github4s", 17, List("bug", "code review"))
 val response = assignedLabelList.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -354,7 +360,7 @@ You can remove a label from an issue with the following parameters:
  To remove an existing label from an issue:
 
 ```scala mdoc:compile-only
-val removedLabelList = Github[IO](accessToken).issues.removeLabel("47degrees", "github4s", 17, "bug")
+val removedLabelList = gh.issues.removeLabel("47degrees", "github4s", 17, "bug")
 val response = removedLabelList.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -378,7 +384,7 @@ You can list available assignees for issues in repo with the following parameter
  To list available assignees:
 
 ```scala mdoc:compile-only
-val assignees = Github[IO](accessToken).issues.listAvailableAssignees("47degrees", "github4s")
+val assignees = gh.issues.listAvailableAssignees("47degrees", "github4s")
 val response = assignees.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -414,7 +420,7 @@ You can list the milestone for a particular organization and repository with `li
  To list the milestone for owner `47deg` and repository `github4s`:
 
 ```scala mdoc:compile-only
-val milestones = Github[IO](accessToken).issues.listMilestones("47degrees", "github4s", Some("open"), None, None)
+val milestones = gh.issues.listMilestones("47degrees", "github4s", Some("open"), None, None)
 val response = milestones.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/organization.md b/docs/docs/organization.md
index 2a15f99b0..00f56d763 100644
--- a/docs/docs/organization.md
+++ b/docs/docs/organization.md
@@ -14,21 +14,27 @@ with Github4s, you can interact with:
 - [Outside Collaborators](#outside-collaborators)
   - [List outside collaborators](#list-outside-collaborators)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Members
 
@@ -44,7 +50,7 @@ You can list the members for a particular organization with `listMembers`; it ta
 To list the members for organization `47deg`:
 
 ```scala mdoc:compile-only
-val listMembers = Github[IO](accessToken).organizations.listMembers("47deg")
+val listMembers = gh.organizations.listMembers("47deg")
 val response = listMembers.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -69,7 +75,7 @@ You can list the outside collaborators of your organization with `listOutsideCol
 To list the outside collaborators for organization `47deg`:
 
 ```scala mdoc:compile-only
-val outsideCollaborators = Github[IO](accessToken).organizations.listOutsideCollaborators("47deg")
+val outsideCollaborators = gh.organizations.listOutsideCollaborators("47deg")
 val response = outsideCollaborators.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/project.md b/docs/docs/project.md
index 40afd952c..33d37f468 100644
--- a/docs/docs/project.md
+++ b/docs/docs/project.md
@@ -3,7 +3,7 @@ layout: docs
 title: Project API
 permalink: project
 ---
- 
+
 # Project API
 
 Note: The Projects API is currently available for developers to preview. During the preview period,
@@ -22,21 +22,27 @@ with Github4s, you can interact with:
   - [Cards](#cards)
     - [List project cards](#list-project-cards-by-column)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.effect.IO`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Project
 
@@ -53,7 +59,7 @@ You can list the projects for a particular repository with `listProjectsReposito
 To list the projects for owner `47deg` and repository `github4s`:
 
 ```scala mdoc:compile-only
-val listProjectsRepository = Github[IO](accessToken).projects.listProjectsRepository(
+val listProjectsRepository = gh.projects.listProjectsRepository(
     owner = "47deg",
     repo = "github4s",
     headers = Map("Accept" -> "application/vnd.github.inertia-preview+json"))
@@ -83,7 +89,7 @@ You can list the project for a particular organization with `listProjects`; it t
 To list the projects for organization `47deg`:
 
 ```scala mdoc:compile-only
-val listProjects = Github[IO](accessToken).projects.listProjects(
+val listProjects = gh.projects.listProjects(
     org = "47deg",
     headers = Map("Accept" -> "application/vnd.github.inertia-preview+json"))
 val response = listProjects.unsafeRunSync()
@@ -112,7 +118,7 @@ You can list the columns for a particular project with `listColumns`; it takes a
 To list the columns for project_id `1910444`:
 
 ```scala mdoc:compile-only
-val listColumns = Github[IO](accessToken).projects.listColumns(
+val listColumns = gh.projects.listColumns(
     project_id = 1910444,
     headers = Map("Accept" -> "application/vnd.github.inertia-preview+json"))
 val response = listColumns.unsafeRunSync()
@@ -135,7 +141,7 @@ See [the API doc](https://developer.github.com/v3/projects/columns/#list-project
 You can list the cards for a particular column with `listCards`; it takes as arguments:
 
 - `column_id`: column id for which we want to retrieve the cards.
-- `archived_state`: filters the project cards that are returned by the card's state. 
+- `archived_state`: filters the project cards that are returned by the card's state.
 Can be one of `all`,`archived`, or `not_archived`. Default: `not_archived`, optional.
 - `pagination`: Limit and Offset for pagination, optional.
 - `header`: headers to include in the request, optional.
@@ -143,7 +149,7 @@ Can be one of `all`,`archived`, or `not_archived`. Default: `not_archived`, opti
 To list the columns for project_id `8271018`:
 
 ```scala mdoc:compile-only
-val listCards = Github[IO](accessToken).projects.listCards(
+val listCards = gh.projects.listCards(
     column_id = 8271018,
     headers = Map("Accept" -> "application/vnd.github.inertia-preview+json"))
 val response = listCards.unsafeRunSync()
@@ -158,3 +164,4 @@ The `result` on the right is the corresponding [List[Card]][card-scala].
 See [the API doc](https://developer.github.com/v3/projects/cards/#list-project-cards) for full reference.
 
 [card-scala]: https://github.com/47degrees/github4s/blob/master/github4s/src/main/scala/github4s/domain/Project.scala
+[http4s-client]: https://http4s.org/v0.21/client/
diff --git a/docs/docs/pull_request.md b/docs/docs/pull_request.md
index 2bd4a6746..3b750fd1d 100644
--- a/docs/docs/pull_request.md
+++ b/docs/docs/pull_request.md
@@ -18,20 +18,27 @@ with Github4s, you can interact with:
   - [List reviews](#list-pull-request-reviews)
   - [Get a review](#get-an-individual-review)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
+
+import scala.concurrent.ExecutionContext.global
+
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-implicit val IOContextShift = IO.contextShift(global)
 val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
 ```
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
-
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
 
 ## Pull requests
 
@@ -45,7 +52,7 @@ You can get a single pull request for a repository using `get`; it takes as argu
 To get a single pull request:
 
 ```scala mdoc:compile-only
-val getPullRequest = Github[IO](accessToken).pullRequests.getPullRequest("47degrees", "github4s", 102)
+val getPullRequest = gh.pullRequests.getPullRequest("47degrees", "github4s", 102)
 val response = getPullRequest.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -70,7 +77,7 @@ by popularity:
 ```scala mdoc:compile-only
 import github4s.domain._
 val prFilters = List(PRFilterOpen, PRFilterSortPopularity)
-val listPullRequests = Github[IO](accessToken).pullRequests.listPullRequests("scala", "scala", prFilters)
+val listPullRequests = gh.pullRequests.listPullRequests("scala", "scala", prFilters)
 val response = listPullRequests.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -92,7 +99,7 @@ You can also list the files for a pull request using `listFiles`; it takes as ar
 To list the files for a pull request:
 
 ```scala mdoc:compile-only
-val listPullRequestFiles = Github[IO](accessToken).pullRequests.listFiles("47degrees", "github4s", 102)
+val listPullRequestFiles = gh.pullRequests.listFiles("47degrees", "github4s", 102)
 val response = listPullRequestFiles.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -121,7 +128,7 @@ On the one hand, we can pass the following parameters:
 ```scala mdoc:compile-only
 import github4s.domain.NewPullRequestData
 
-val createPullRequestData = Github[IO](accessToken).pullRequests.createPullRequest(
+val createPullRequestData = gh.pullRequests.createPullRequest(
   "47deg",
   "github4s",
   NewPullRequestData("title", "body"),
@@ -142,7 +149,7 @@ instead of the title and body.
 
 ```scala mdoc:compile-only
 import github4s.domain.NewPullRequestIssue
-val createPullRequestIssue = Github[IO](accessToken).pullRequests.createPullRequest(
+val createPullRequestIssue = gh.pullRequests.createPullRequest(
   "47deg",
   "github4s",
   NewPullRequestIssue(105),
@@ -170,7 +177,7 @@ You can list the reviews for a pull request using `listReviews`; it takes as arg
 As an example, if we wanted to see all the reviews for pull request 139 of `47degrees/github4s`:
 
 ```scala mdoc:compile-only
-val listReviews = Github[IO](accessToken).pullRequests.listReviews(
+val listReviews = gh.pullRequests.listReviews(
   "47deg",
   "github4s",
   139)
@@ -196,7 +203,7 @@ You can get an individual review for a pull request using `getReview`; it takes
 As an example, if we wanted to see review 39355613 for pull request 139 of `47degrees/github4s`:
 
 ```scala mdoc:compile-only
-val review = Github[IO](accessToken).pullRequests.getReview(
+val review = gh.pullRequests.getReview(
   "47deg",
   "github4s",
   139,
diff --git a/docs/docs/repository.md b/docs/docs/repository.md
index 7c93a8b9c..5def773c3 100644
--- a/docs/docs/repository.md
+++ b/docs/docs/repository.md
@@ -26,21 +26,27 @@ with Github4s, you can interact with:
   - [List statuses for a specific Ref](#list-statuses-for-a-specific-ref)
   - [Get the combined status of a specific Ref](#get-the-combined-status-for-a-specific-ref)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Repositories
 
@@ -53,8 +59,7 @@ You can get a repository using `get`; it takes as arguments:
 To get a repository:
 
 ```scala mdoc:compile-only
-val getRepo =
-  Github[IO](accessToken).repos.get("47degrees", "github4s")
+val getRepo = gh.repos.get("47degrees", "github4s")
 val response = getRepo.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -80,7 +85,7 @@ takes as arguments:
 To list the repositories for an organization:
 
 ```scala mdoc:compile-only
-val listOrgRepos = Github[IO](accessToken).repos.listOrgRepos("47deg")
+val listOrgRepos = gh.repos.listOrgRepos("47deg")
 val response = listOrgRepos.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -105,7 +110,7 @@ takes as arguments:
 To list the repositories for a user:
 
 ```scala mdoc:compile-only
-val listUserRepos = Github[IO](accessToken).repos.listUserRepos("rafaparadela")
+val listUserRepos = gh.repos.listUserRepos("rafaparadela")
 val response = listUserRepos.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -131,8 +136,7 @@ You can list contributors using `listContributors`, it takes as arguments:
 To list contributors:
 
 ```scala mdoc:compile-only
-val listContributors =
-  Github[IO](accessToken).repos.listContributors("47degrees", "github4s", Some("true"))
+val listContributors = gh.repos.listContributors("47degrees", "github4s", Some("true"))
 val response = listContributors.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -156,8 +160,7 @@ You can list collaborators using `listCollaborators`, it takes as arguments:
 For more information take a look at [the API doc](https://developer.github.com/v3/repos/collaborators/#parameters).
 
 ```scala mdoc:compile-only
-val listCollaborators =
-  Github[IO](accessToken).repos.listCollaborators("47degrees", "github4s", Some("all"))
+val listCollaborators = gh.repos.listCollaborators("47degrees", "github4s", Some("all"))
 val response = listCollaborators.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -188,7 +191,7 @@ To list commits:
 
 ```scala mdoc:compile-only
 val listCommits =
-  Github[IO](accessToken).repos.listCommits(
+  gh.repos.listCommits(
   "47deg",
   "github4s",
   Some("d3b048c1f500ee5450e5d7b3d1921ed3e7645891"),
@@ -221,7 +224,7 @@ To list branches:
 
 ```scala mdoc:compile-only
 val listBranches =
-  Github[IO](accessToken).repos.listBranches(
+  gh.repos.listBranches(
   "47deg",
   "github4s")
 val response = listBranches.unsafeRunSync()
@@ -250,8 +253,7 @@ You can get contents using `getContents`, it takes as arguments:
 To get contents:
 
 ```scala mdoc:compile-only
-val getContents =
-  Github[IO](accessToken).repos.getContents("47degrees", "github4s", "README.md", Some("heads/master"))
+val getContents = gh.repos.getContents("47degrees", "github4s", "README.md", Some("heads/master"))
 val response = getContents.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -283,7 +285,7 @@ To create a release:
 
 ```scala mdoc:compile-only
 val createRelease =
-  Github[IO](accessToken).repos.createRelease("47degrees", "github4s", "v0.1.0", "v0.1.0", "New access token", Some("master"), Some(false), Some(false))
+  gh.repos.createRelease("47degrees", "github4s", "v0.1.0", "v0.1.0", "New access token", Some("master"), Some(false), Some(false))
 val response = createRelease.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -310,8 +312,7 @@ You can create a status using `createStatus`; it takes as arguments:
 To create a status:
 
 ```scala mdoc:compile-only
-val createStatus =
-  Github[IO](accessToken).repos.createStatus("47degrees", "github4s", "aaaaaa", "pending", None, None, None)
+val createStatus = gh.repos.createStatus("47degrees", "github4s", "aaaaaa", "pending", None, None, None)
 val response = createStatus.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -334,8 +335,7 @@ You can also list statuses through `listStatuses`; it take as arguments:
 To list the statuses for a specific ref:
 
 ```scala mdoc:compile-only
-val listStatuses =
-  Github[IO](accessToken).repos.listStatuses("47degrees", "github4s", "heads/master")
+val listStatuses = gh.repos.listStatuses("47degrees", "github4s", "heads/master")
 val response = listStatuses.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -354,8 +354,7 @@ Lastly, you can also get the combined status thanks to `getCombinedStatus`; it t
 arguments as the operation listing statuses:
 
 ```scala mdoc:compile-only
-val combinedStatus =
-  Github[IO](accessToken).repos.getCombinedStatus("47degrees", "github4s", "heads/master")
+val combinedStatus = gh.repos.getCombinedStatus("47degrees", "github4s", "heads/master")
 val response = combinedStatus.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/team.md b/docs/docs/team.md
index 3cbd5cb24..b84bc3b32 100644
--- a/docs/docs/team.md
+++ b/docs/docs/team.md
@@ -12,21 +12,27 @@ with Github4s, you can interact with:
 - [Team](#team)
   - [List team](#list-team)
 
-The following examples assume the following imports and token:
+The following examples assume the following code:
 
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
 
-implicit val IOContextShift = IO.contextShift(global)
-val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
-```
+import scala.concurrent.ExecutionContext.global
 
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
+val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
+```
 
 ## Team
 
@@ -40,7 +46,7 @@ You can list the teams for a particular organization with `listTeams`; it takes
 To list the teams for organization `47deg`:
 
 ```scala mdoc:compile-only
-val listTeams = Github[IO](accessToken).teams.listTeams("47deg")
+val listTeams = gh.teams.listTeams("47deg")
 val response = listTeams.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
diff --git a/docs/docs/user.md b/docs/docs/user.md
index 2c1b8a35e..ba065e1ef 100644
--- a/docs/docs/user.md
+++ b/docs/docs/user.md
@@ -15,20 +15,25 @@ with Github4s, you can interacts with:
   - [Get a list of users](#get-a-list-of-users)
   - [List users followed by another user](#list-users-followed-by-another-user)
 
-The following examples assume the following imports and token:
-
 ```scala mdoc:silent
+import java.util.concurrent._
+
+import cats.effect.{Blocker, ContextShift, IO}
 import github4s.Github
-import github4s.GithubIOSyntax._
-import cats.effect.IO
-import scala.concurrent.ExecutionContext.Implicits.global
+import org.http4s.client.{Client, JavaNetClientBuilder}
+
+import scala.concurrent.ExecutionContext.global
+
+val httpClient: Client[IO] = {
+  val blockingPool = Executors.newFixedThreadPool(5)
+  val blocker = Blocker.liftExecutorService(blockingPool)
+  implicit val cs: ContextShift[IO] = IO.contextShift(global)
+  JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
+}
 
-implicit val IOContextShift = IO.contextShift(global)
 val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
+val gh = Github[IO](httpClient, accessToken)
 ```
-They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
-
-LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
 
 ## Users
 
@@ -41,7 +46,7 @@ You can get a user using `get`, it takes as argument:
 - `username`: of the user to retrieve.
 
 ```scala mdoc:compile-only
-val getUser = Github[IO](accessToken).users.get("rafaparadela")
+val getUser = gh.users.get("rafaparadela")
 val response = getUser.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -61,7 +66,7 @@ Get information of the authenticated user making the API call.
 You can get an authenticated user using `getAuth`:
 
 ```scala mdoc:compile-only
-val getAuth = Github[IO](accessToken).users.getAuth()
+val getAuth = gh.users.getAuth()
 val response = getAuth.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -82,7 +87,7 @@ You can get a list of users using `getUsers`, it takes as arguments:
 - `pagination`: Limit and Offset for pagination.
 
 ```scala mdoc:compile-only
-val getUsers = Github[IO](accessToken).users.getUsers(1)
+val getUsers = gh.users.getUsers(1)
 val response = getUsers.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -105,7 +110,7 @@ You can get a list of users followed by another user using `getFollowing`, it ta
 - `username`: of the user to retrieve.
 
 ```scala mdoc:compile-only
-val getFollowing = Github[IO](accessToken).users.getFollowing("rafaparadela")
+val getFollowing = gh.users.getFollowing("rafaparadela")
 val response = getFollowing.unsafeRunSync()
 response.result match {
   case Left(e) => println(s"Something went wrong: ${e.getMessage}")
@@ -118,3 +123,4 @@ The `result` on the right is the corresponding [List[User]][user-scala].
 See [the API doc](https://developer.github.com/v3/users/followers/#list-users-followed-by-another-use) for full reference.
 
 [user-scala]: https://github.com/47degrees/github4s/blob/master/github4s/src/main/scala/github4s/domain/User.scala
+[http4s-client]: https://http4s.org/v0.21/client/