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/serialization.tree

@@ -0,0 +1,24 @@
+<?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>
+        <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/serialization.md

@@ -0,0 +1,70 @@
+[//]: # (title: Serialization)
+
+**Serialization** is the process of converting data used by an application to a format that can be transferred over a
+network, or stored in a database or a file. Deserialization is the opposite process of converting external data back into a runtime object.
+Together, they are essential to most applications that exchange data with third parties.
+
+Some data serialization formats, such as [JSON](https://www.json.org/json-en.html) and [Protocol Buffers](https://protobuf.dev/), are particularly common.
+These formats are language-neutral and platform-neutral, so you can use them to exchange data between systems written in any modern language.
+Kotlin provides this functionality through the [`kotlinx.serialization` libraries](#kotlin-serialization-libraries),
+which support multiple platforms and data formats.
+
+If you're new to serialization in Kotlin, we recommend starting with the [Get Started with Serialization](serialization-get-started.md) tutorial.
+It walks you through adding the Kotlin serialization library to your project and shows you how to serialize and deserialize your first class.
+
+<a href="serialization-get-started.md"><img src="get-started-serialization.svg" width="700" alt="Get started with serialization" style="block"/></a>
+
+## Kotlin serialization libraries
+
+Kotlin serialization offers support for all platforms, including JVM, JavaScript, and Native.
+You can use the same [dependency declaration](serialization-get-started.md#add-plugins-and-dependencies-for-kotlin-serialization) regardless of the target platform.
+
+Kotlin serialization supports various serialization formats, such as JSON, CBOR, and Protocol buffers through different serialization format libraries.
+These libraries build on the core `kotlinx.serialization` library.
+For the complete list of supported serialization formats, see [Supported serialization formats](#supported-serialization-formats).
+
+All Kotlin serialization format libraries are part of the `org.jetbrains.kotlinx:` group, with names
+starting with `kotlinx-serialization-` and suffixes that reflect the serialization format.
+For example:
+
+* `org.jetbrains.kotlinx:kotlinx-serialization-json` provides JSON serialization.
+* `org.jetbrains.kotlinx:kotlinx-serialization-cbor` provides CBOR serialization.
+
+The `kotlinx.serialization` libraries follow their own versioning, independent of Kotlin.
+You can find the latest release versions on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases).
+
+## Supported serialization formats
+
+`kotlinx.serialization` includes serialization format libraries for various formats:
+
+| Format       | Artifact ID                                                                                                                    | Platform                | Status       |
+|--------------|--------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------|
+| [JSON](https://www.json.org/json-en.html)            | [`kotlinx-serialization-json`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#json)             | All supported platforms | Stable       |
+| [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md) | [`kotlinx-serialization-hocon`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#hocon)           | JVM only                | Experimental |
+| [Protocol Buffers](https://protobuf.dev/)            | [`kotlinx-serialization-protobuf`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#protobuf)     | All supported platforms | Experimental |
+| [CBOR](https://cbor.io/)                             | [`kotlinx-serialization-cbor`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#cbor)             | All supported platforms | Experimental |
+| [Properties](https://en.wikipedia.org/wiki/.properties) | [`kotlinx-serialization-properties`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties) | All supported platforms | Experimental |
+
+All serialization format libraries, except for the JSON serialization library (`kotlinx-serialization-json`), are [Experimental](components-stability.md). Their APIs might change at any time.
+For more details about JSON serialization, see [JSON serialization overview](configure-json-serialization.md).
+
+There are also community-maintained libraries that support more serialization formats, such as [YAML](https://yaml.org/) or [Apache Avro](https://avro.apache.org/).
+
+You can find out more about experimental serialization formats in [Alternative and custom serialization formats](alternative-serialization-formats.md).
+
+## Supported serialization types
+
+Kotlin serialization supports a variety of built-in types, including all primitive types and most composite types from the Kotlin standard library like the `List` type.
+For more information, see [Serialize built-in types](serialization-serialize-builtin-types.md).
+
+Additionally, classes annotated with `@Serializable` are fully supported for serialization, enabling the conversion of class instances to and from formats like JSON.
+For more information, see [Serialize classes](serialization-customization-options.md).
+
+## What's next
+
+* Learn the basics of Kotlin serialization in the [Get started with serialization tutorial](serialization-get-started.md).
+* See how the Kotlin serialization library processes [primitives, collections, and other built-in types](serialization-serialize-builtin-types.md)
+* Explore more complex JSON serialization scenarios in the [JSON serialization overview](configure-json-serialization.md).
+* Dive into [Serialize classes](serialization-customization-options.md) to learn how to serialize classes and modify the default behavior of the `@Serializable` annotation.
+* Learn how to define and customize your own serializers in [Create custom serializers](serialization-custom-serializers.md).
+* See how to serialize different types through a shared base type in [Serialize polymorphic classes](serialization-polymorphism.md).

docs-website/v.list

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/stardust/vars.dtd">
+
+<!-- Variables to be used throughout the documentation -->
+<vars>
+
+</vars>

docs-website/writerside.cfg

@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
+
+<ihp version="2.0">
+    <module name="serialization"/>
+    <topics dir="topics"/>
+    <images dir="images"/>
+    <vars src="v.list"/> <!-- be careful with renaming the file, might lead to build errors / bugs -->
+    <settings>
+        <!-- ToC within topics, usually displayed on the left, depth is measured by header levels -->
+        <default-property element-name="chapter" property-name="show-structure-depth" value="2"/>
+        <wrs-supernova use-version="242.21870"/>
+    </settings>
+    <instance src="serialization.tree"/>
+</ihp>