feat: rewriting documentation to integrate to kotlinlang.org

docs-website/cfg/buildprofiles.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<buildprofiles>
+    <variables>
+        <enable-browser-edits>true</enable-browser-edits>
+        <browser-edits-url>https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/</browser-edits-url>
+        <allow-indexable-eaps>true</allow-indexable-eaps>
+    </variables>
+    <build-profile product="serialization"/>
+</buildprofiles>

docs-website/labels.list

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE labels SYSTEM "https://resources.jetbrains.com/writerside/1.0/labels-list.dtd">
+<labels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/labels.xsd">
+
+    <primary-label id="experimental-general" name="Experimental" short-name="Experimental" href="components-stability.html#stability-levels-explained" color="red">The feature is Experimental. It may be dropped or changed at any time. Use it only for evaluation purposes.</primary-label>
+    <primary-label id="experimental-opt-in" name="Experimental" short-name="Experimental" href="components-stability.html#stability-levels-explained" color="red" >The feature is Experimental. It may be dropped or changed at any time. Opt-in is required (see the details below), and you should use it only for evaluation purposes.</primary-label>
+    <primary-label id="alpha" name="Alpha" short-name="α" href="components-stability.html#stability-levels-explained" color="strawberry">The feature is in Alpha. It may change incompatibly and require manual migration in the future.</primary-label>
+    <primary-label id="beta" name="Beta" short-name="β" href="components-stability.html#stability-levels-explained" color="tangerine">The feature is in Beta. It is almost stable, but migration steps may be required in the future. We'll do our best to minimize any changes you have to make.</primary-label>
+    <primary-label id="advanced" name="Advanced" short-name="☆" color="purple"></primary-label>
+    <primary-label id="eap" name="EAP" short-name="EAP" color="red">This functionality is available only in the latest EAP version.</primary-label>
+
+    <secondary-label id="eap" name="EAP" color="red">This functionality is available only in the latest EAP version.</secondary-label>
+</labels>

docs-website/serialization.tree

@@ -0,0 +1,25 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+<instance-profile id="serialization" name="Serialization" start-page="serialization.md">
+    <snippet id="serialization">
+        <toc-element topic="serialization.md" toc-title="Introduction"/>
+        <toc-element toc-title="Get started">
+            <toc-element topic="serialization-get-started.md"/>
+            <toc-element topic="serialization-serialize-builtin-types.md"/>
+            <toc-element topic="serialization-customization-options.md"/>
+        </toc-element>
+        <toc-element toc-title="Configure JSON serialization">
+            <toc-element topic="configure-json-serialization.md" toc-title="Overview"/>
+            <toc-element topic="serialization-json-configuration.md"/>
+            <toc-element topic="serialization-json-elements.md"/>
+            <toc-element topic="serialization-transform-json.md" toc-title="JSON transformation"/>
+            <toc-element topic="serialization-json-io-sources.md"/>
+        </toc-element>
+        <toc-element topic="serialization-polymorphism.md"/>
+        <toc-element toc-title="Custom serializers">
+            <toc-element topic="create-custom-serializers.md"/>
+            <toc-element topic="third-party-classes.md"/>
+        </toc-element>
+        <toc-element topic="alternative-serialization-formats.md" toc-title="Alternative serialization formats"/>
+    </snippet>
+</instance-profile>

docs-website/topics/configure-json-serialization.md

@@ -0,0 +1,85 @@
+[//]: # (title: JSON serialization overview)
+
+The Kotlin serialization library allows you to easily convert Kotlin objects to JSON and back.
+The [`Json`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/) class is the primary tool for this, offering flexibility in how JSON is generated and parsed.
+You can configure `Json` instances to handle specific JSON behaviors or use its default instance for basic tasks.
+
+With the `Json` class, you can:
+
+* Serialize Kotlin objects to JSON strings using the [`encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function.
+* Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function.
+* [Work directly with the `JsonElement`](serialization-json-elements.md) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions.
+* Use [Experimental](components-stability.md#stability-levels-explained) extension functions to [serialize and deserialize I/O sources](serialization-json-io-sources.md) without creating intermediate strings, including JVM streams as well as [`kotlinx-io`](https://github.com/Kotlin/kotlinx-io) and [Okio](https://square.github.io/okio/) types.
+
+Before you start, import the following declarations from the serialization library:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+```
+
+Here's a simple example that uses the default `Json` instance to show how JSON serialization works in Kotlin:
+
+```kotlin
+// Imports declarations from the serialization library
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+data class User(val name: String, val age: Int)
+
+fun main() {
+    // Uses the default Json instance
+    val json = Json
+
+    // Creates a User object
+    val user = User("Alice", 30)
+
+    // Converts the User object to a JSON string
+    val jsonString = json.encodeToString(user)
+    println(jsonString)
+    // {"name":"Alice","age":30}
+
+    // Converts the JSON string back to a User object
+    val deserializedUser = json.decodeFromString<User>(jsonString)
+    println(deserializedUser)
+    // User(name=Alice, age=30)
+//sampleEnd
+}
+```
+{kotlin-runnable="true" id="first-json-example"}
+
+In addition to using the default configuration, you can [customize the `Json` instance](serialization-json-configuration.md) for specific use cases,
+such as ignoring unknown keys:
+
+```kotlin
+// Imports declarations from the serialization library
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+data class Project(val name: String)
+
+// Configures a Json instance to ignore unknown keys
+val customJson = Json {
+    ignoreUnknownKeys = true
+}
+
+fun main() {
+    val data = customJson.decodeFromString<Project>("""
+        {"name":"kotlinx.serialization","language":"Kotlin"}
+    """)
+    println(data)
+    // Project(name=kotlinx.serialization)
+}
+//sampleEnd
+```
+{kotlin-runnable="true" id="first-json-instance-example"}
+
+## What's next
+
+* Learn how to [customize `Json` instances](serialization-json-configuration.md) to address different use cases for serialization and deserialization.
+* Explore [advanced JSON element handling](serialization-json-elements.md) to manipulate and work with JSON data before it is parsed or serialized.
+* Discover how to [transform JSON during serialization and deserialization](serialization-transform-json.md) for more control over your data.