From c1b059dcbf9a6cefc5cc8da83bb9fd3554e79be5 Mon Sep 17 00:00:00 2001
From: Arek Nawo <areknawo@areknawo.com>
Date: Mon, 17 Jul 2023 13:59:26 +0200
Subject: [PATCH] docs: Add Variants docs

---
 .../src/content/docs/2-managing-metadata.md   |  8 ++-
 .../src/content/docs/4-configuring-vrite.md   | 16 +++++
 .../docs/src/content/docs/7-javascript-sdk.md | 66 ++++++++++---------
 3 files changed, 58 insertions(+), 32 deletions(-)

diff --git a/apps/docs/src/content/docs/2-managing-metadata.md b/apps/docs/src/content/docs/2-managing-metadata.md
index f69d0551..a5e8e439 100644
--- a/apps/docs/src/content/docs/2-managing-metadata.md
+++ b/apps/docs/src/content/docs/2-managing-metadata.md
@@ -35,7 +35,7 @@ In Vrite you can assign existing tags to the content piece by using the _Select
 
 Assigning members to the content piece helps you manage the work in the Kanban better, especially in larger teams. To do so you use the _Assign members_ dropdown to search and select members in your workspace who you’d like to assign to the content piece.
 
-![Assigning members ](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/KweUZD3FRhnQCVbSX6-if.png)
+![Assigning members to content piece](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/KweUZD3FRhnQCVbSX6-if.png)
 
 ## Custom JSON Data
 
@@ -60,3 +60,9 @@ When needed, Vrite Extensions can provide _Content Piece Views_ to e.g. manage n
 ![Dev.to extension's content piece view](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/FBJlSqp-X712TBA5cmdXv.png)
 
 You can read more about Vrite Extensions [here](/vrite-extensions).
+
+## Variants
+
+You can switch between _Content Piece Variants_ in the _Variants_ section. Once activated, all changes will be applied to the specified Variant. You can go back to the _Base Variant_ by clicking on and deactivating the currently-selected one.
+
+![Content Piece Variants section](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/pDAdkIDD7ECTErujXJCTD.png)
diff --git a/apps/docs/src/content/docs/4-configuring-vrite.md b/apps/docs/src/content/docs/4-configuring-vrite.md
index d67023a6..d334f075 100644
--- a/apps/docs/src/content/docs/4-configuring-vrite.md
+++ b/apps/docs/src/content/docs/4-configuring-vrite.md
@@ -266,3 +266,19 @@ At the bottom of the same section, you can provide your Prettier configuration i
 The _Metadata_ section is where you can configure options related to content piece metadata. Right now, it enables you to set a custom pattern for a **canonical link** which will be used by default for any content piece lacking a custom canonical link. This can be useful if you’re running a publication based on Vrite and cross-post often to different frontends or platforms.
 
 ![Metadata settings section](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/bHQsixD8DlNnm-w_i5u8m.png)
+
+## Managing Variants
+
+_Content Piece Variants_ allow you to create and manage different alterations of your content pieces. They serve as “overlays” on top of your _Base Variant_, i.e. the piece’s default content and metadata and are great for managing multi-language content or for slightly customizing your content for different endpoints.
+
+You can create and manage your Variants in the _Variants_ settings section.
+
+![Variants settings section](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/R4DOfYmkxcR61c0_oIBCs.png)
+
+The following details can be configured:
+
+- _Label_ — label for identifying the Variant
+- _Name_ — name for the Variant; You’ll be able to use it to retrieve the Content Piece Variants through the API;
+- _Description_ — optional description for additional details;
+
+![Configuring new Variant](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/HkvBrnygrWRGUMfjg35PD.png)
diff --git a/apps/docs/src/content/docs/7-javascript-sdk.md b/apps/docs/src/content/docs/7-javascript-sdk.md
index f4ca4b9d..8b4da71d 100644
--- a/apps/docs/src/content/docs/7-javascript-sdk.md
+++ b/apps/docs/src/content/docs/7-javascript-sdk.md
@@ -16,7 +16,6 @@ Currently it includes the following parts:
 
 ```shell
 npm i @vrite/sdk
-
 ```
 
 ## Usage
@@ -28,9 +27,9 @@ The Vrite SDK is modular, so you can import only the parts of it you need. On to
 Start by initializing the API client, by importing the library, and providing your API access token:
 
 ```javascript
-import { createClient } from "@vrite/sdk/api";
+import { createClient } from '@vrite/sdk/api';
 const vrite = createClient({
-  token: "[YOUR_API_TOKEN]"
+  token: '[YOUR_API_TOKEN]',
 });
 ```
 
@@ -41,12 +40,12 @@ With the client configured, you can access [all the endpoints of the Vrite API](
 const contentGroups = await vrite.contentGroups.list();
 // Get all content pieces from a content group
 const contentPieces = await vrite.contentPieces.list({
-  contentGroupId: "[CONTENT_GROUP_ID]"
+  contentGroupId: '[CONTENT_GROUP_ID]',
 });
 // Get the entire conten piece with JSON content
 const contentPiece = await vrite.contentPieces.get({
-  id: "[CONTENT_PIECE_ID]",
-  content: true
+  id: '[CONTENT_PIECE_ID]',
+  content: true,
 });
 ```
 
@@ -59,7 +58,11 @@ To explore available endpoints, check out [Vrite API docs](https://generator.swa
 The JSON output, based on the [ProseMirror](https://prosemirror.net/) library powering the Vrite Editor, is very versatile and easy to process, making it the ideal choice, no matter how your content has to be delivered. Content transformers help with this process by further simplifying the processing of these recursive JSON trees to output strings.
 
 ```javascript
-import { createContentTransformer, gfmTransformer, htmlTransformer } from "@vrite/sdk/transformers";
+import {
+  createContentTransformer,
+  gfmTransformer,
+  htmlTransformer,
+} from '@vrite/sdk/transformers';
 
 const sampleVriteJSON = {
   // ...
@@ -72,13 +75,13 @@ const htmlOutput = htmlTransformer(sampleVriteJSON);
 const customContentTransformer = createContentTransformer({
   applyInlineFormatting(type, attrs, content) {
     switch (type) {
-      case "link":
+      case 'link':
         return `<a href="${attrs.href}">${content}</a>`;
-      case "bold":
+      case 'bold':
         return `<strong>${content}</strong>`;
-      case "code":
+      case 'code':
         return `<code>${content}</code>`;
-      case "italic":
+      case 'italic':
         return `<em>${content}</em>`;
       default:
         return content;
@@ -86,24 +89,24 @@ const customContentTransformer = createContentTransformer({
   },
   transformNode(type, attrs, content) {
     switch (type) {
-      case "paragraph":
+      case 'paragraph':
         return `<p>${content}</p>`;
-      case "heading":
+      case 'heading':
         return `<h${attrs?.level || 1}>${content}</h${attrs?.level || 1}>`;
-      case "blockquote":
+      case 'blockquote':
         return `<blockquote>${content}</blockquote>`;
-      case "bulletList":
+      case 'bulletList':
         return `<ul>${content}</ul>`;
-      case "orderedList":
+      case 'orderedList':
         return `<ol>${content}</ol>`;
-      case "listItem":
+      case 'listItem':
         return `<li>${content}</li>`;
-      case "horizontalRule":
+      case 'horizontalRule':
         return `<hr/>`;
       default:
         return content;
     }
-  }
+  },
 });
 ```
 
@@ -116,17 +119,17 @@ Vrite Astro integration makes integrating Vrite with your Astro-powered website
 Start by adding the Vrite plugin into the Astro config:
 
 ```javascript
-import { defineConfig } from "astro/config";
-import { vritePlugin } from "@vrite/sdk/astro";
+import { defineConfig } from 'astro/config';
+import { vritePlugin } from '@vrite/sdk/astro';
 export default defineConfig({
   integrations: [
     // ...
     vritePlugin({
-      accessToken: "[YOUR_ACCESS_TOKEN]",
-      contentGroupId: "[CONTENT_GROUP_ID]"
-    })
+      accessToken: '[YOUR_ACCESS_TOKEN]',
+      contentGroupId: '[CONTENT_GROUP_ID]',
+    }),
     // ...
-  ]
+  ],
 });
 ```
 
@@ -140,7 +143,7 @@ If you're using **TypeScript**, add the following to your _tsconfig.json_, under
 
 Now you can import from a `virtual:vrite` module that provides configured API client, along with a few utils for integrating Vrite with Astro:
 
-```html
+```astro
 ---
 import { Content, client, getContentPieces, getStaticPaths } from "virtual:vrite";
 
@@ -153,15 +156,16 @@ export getStaticPaths;
 ---
 
 <!-- Renders the Vrite content piece, specified by ID or slug -->
-<content contentPieceId="..." slug="..." />
+<Content contentPieceId="..." slug="..." />
 ```
 
-- `Content` — renders Vrite content piece specified either by ID (`contentPieceId` prop) or a slug (`slug` prop); Useful when in SSR mode;
+- `Content` — renders Vrite content piece specified either by ID (`contentPieceId` prop) or a slug (`slug` prop); Also accepts Variant name or ID (`variant` prop) and direct JSON content input (`content` prop);
 - `client` — pre-configured Vrite API client for easy access;
-  - `getContentPieces` — retrieves content pieces from the content group specified in the config file. Accepts an object with the following properties:
+- `getContentPieces` — retrieves content pieces from the content group specified in the config file. Accepts an object with the following properties:
   - `limit?: number | "all" = 50` — how many content pieces to retrieve; `"all"` retrieves all of them, in batches of 50;
   - `startPage?: number = 1` — if `limit` is a number and pagination is used, what page to start retrieving content pieces from?
-  - `tagId?: string` — Tag ID, if you want to filter results by specific tag.
+  - `tagId?: string` — Tag ID, if you want to filter results by specific tag;
+  - `variant?: string` — Variant name or ID.
 - `getStaticPaths` — shortcut function for easy re-export when using Vrite SSG and inside _[slug].astro_ file. It returns `params.slug` as the content piece's slug and all basic content piece properties as `props`.
 
-For a more detailed guide on using the Vrite Astro integration, [check out this blog post](https://vrite.io/blog/start-programming-blog-in-minutes-with-astro-and-vrite/).
+For a more detailed guide on using the Vrite Astro integration, [check out this blog post](https://vrite.io/blog/start-programming-blog-in-minutes-with-astro-and-vrite/).
\ No newline at end of file