About integrations.

build.sbt

@@ -167,12 +167,17 @@ ThisBuild / githubWorkflowAddedJobs ++= Seq(
 ThisBuild / tlSitePublishBranch := Some("master")
 lazy val docs = project
   .in(file("site"))
-  .dependsOn(core.jvm)
+  .dependsOn(core.jvm, circe.jvm)
   .enablePlugins(TypelevelSitePlugin)
   .settings(
     scalacOptions --= Seq(
       "-Wunused:locals",
     ),
+    libraryDependencies ++= Seq(
+      "io.circe"      %%% "circe-core"    % circeVersion,
+      "io.circe"      %%% "circe-generic" % circeVersion,
+      "io.circe"      %%% "circe-parser"  % circeVersion,
+    ),
     mdocExtraArguments ++= Seq(
       "--exclude", ".*.md",
     ),

docs/conversions.md

@@ -33,6 +33,14 @@ You can use `to` method to convert a record to a `Product`.
 A record can be converted to anything other than `Product` if `Converter` instance is
 given.
 
+From / To JSON
+--------------
+
+Records can be converted from/to JSON using [circe][].  See [Integration with circe] for the
+detail.
+
+[circe]: https://circe.github.io/circe/
+
 Upcast
 ------
 

docs/directory.conf

@@ -6,4 +6,6 @@ laika.navigationOrder = [
   pattern-matching.md
   performance.md
   faq.md
+  integrations
+  appendix
 ]

docs/integrations/circe.md

@@ -0,0 +1,86 @@
+Integration with circe
+======================
+
+Records can be converted to/from JSON by using [circe][].
+
+[circe]: https://circe.github.io/circe/
+
+Installation
+------------
+
+You need an additional module to use records integrated with [circe][].
+
+```scala
+libraryDependencies ++= Seq(
+  "com.github.tarao" %% "record4s-circe" % "@VERSION@"
+),
+```
+
+To JSON
+-------
+
+Importing `Codec.encoder` enables [circe][] to encode records in the ordinary way.
+
+```scala mdoc:mline
+import com.github.tarao.record4s.%
+import com.github.tarao.record4s.circe.Codec.encoder
+import io.circe.generic.auto.*
+import io.circe.syntax.*
+
+val r = %(name = "tarao", age = 3)
+val json = r.asJson.noSpaces
+```
+
+From JSON
+---------
+
+Importing `Codec.encoder` enables [circe][] to decode records in the ordinary way.
+
+```scala mdoc:reset:invisible
+```
+
+```scala mdoc:mline
+import com.github.tarao.record4s.%
+import com.github.tarao.record4s.circe.Codec.decoder
+import io.circe.generic.auto.*
+import io.circe.parser.parse
+
+val json = """{"name":"tarao","age":3}"""
+val r =
+  for {
+    jsonObj <- parse(json)
+  } yield jsonObj.as[% { val name: String; val age: Int }]
+```
+
+ArrayRecord
+-----------
+
+`ArrayRecord` requires no additional module since it is a `Product`, whose conversions
+already supported by [circe][] itself.
+
+```scala mdoc:reset:invisible
+```
+
+```scala mdoc:mline
+import com.github.tarao.record4s.ArrayRecord
+import io.circe.generic.auto.*
+import io.circe.syntax.*
+
+val r = ArrayRecord(name = "tarao", age = 3)
+val json = r.asJson.noSpaces
+```
+
+```scala mdoc:reset:invisible
+```
+
+```scala mdoc:mline
+import com.github.tarao.record4s.ArrayRecord
+import io.circe.generic.auto.*
+import io.circe.parser.parse
+
+val json = """{"name":"tarao","age":3}"""
+val r =
+  for {
+    jsonObj <- parse(json)
+  } yield jsonObj.as[ArrayRecord[(("name", String), ("age", Int))]]
+```