docs: Update docs

apps/docs/src/content/docs/getting-started/concepts.mdx

@@ -0,0 +1,56 @@
+---
+slug: "/getting-started/concepts"
+title: "Concepts"
+---
+
+To better understand Vrite, first get to know a few concepts behind how the platform works.
+
+## Organization
+
+### Content Pieces
+
+A content piece is a **structured JSON content** and related **metadata** taken together. You’ll likely spend a lot of time editing the content in Vrite’s _Editor_ and managing metadata in the _Content Piece_ side panel.
+
+### Content Groups
+
+Content groups group multiple content pieces together, and are represented in the dashboard as e.g. a Kanban column or a folder. You can nest them and reference their IDs when integrating with Vrite’s API.
+
+### Workspaces
+
+Content pieces, content groups, members and related settings are all part of a workspace. You can create and join multiple workspaces to better manage your work (e.g. creating separate workspaces for different websites or projects)
+
+### Variants
+
+Apart from the _Base_ content pieces, you can also create multiple _variants_ of them. Variants allow you to better organize related content, like i18n translations, and other kinds of adaptations. Until metadata or the content of the variant is edited, it’s shared with the base content piece.
+
+## UI
+
+### Main Panel
+
+Main panel is where the bulk of the content creation and mangement work is done. Currently, the main panel is used for the dashboard, editor and Git sync conflict-resolution.
+
+### Side Panel
+
+Side panel is a resizable area to the left of the main panel. It’s meant for secondary activites, like managing content piece metadata, settings, extensions, Git sync etc.
+
+### Sidebar
+
+Sidebar is the primary mean of navigation around Vrite. The options to the top navigate both the main and side panel, while the ones to the bottom — only the side panel.
+
+## API & Customization
+
+### Input/Output Transformers
+
+Input and output transformers are an important part of the Vrite JavaScript SDK and the Git sync integration.
+
+**Output transformers** help transform the content piece’s data to necessary output formats, like HTML or JSX tree for your frontends, or Markdown file when syncing with a Git repo.
+
+**Input transformers** are currently meant exclusively for Git sync and help transform incoming files (e.g. Markdown, MDX, etc.) to HTML string and JSON metadata that can be loaded into Vrite.
+
+### Extensions
+
+The extensions are the primary way of extending the capabilities of Vrite’s platform. With direct access to both Vrite’s REST API and additional functions for customizing UI, they can be used to extend the editor, add easy publishing options and facilitate content synchronization with other platforms.
+
+<Info>
+  While in Beta, the **Vrite Extension System** is in development and currently limited to first-party extensions available only through Vrite Cloud.
+</Info>

apps/docs/src/content/docs/getting-started/introduction.mdx

@@ -0,0 +1,44 @@
+---
+slug: "/getting-started/introduction"
+title: "Getting Started"
+---
+
+Vrite is an [open-source](https://github.com/vriteio/vrite), collaborative developer content platform to create, manage, and deploy product docs, technical blogs, and knowledge bases.
+
+<Important>
+  Vrite is currently in Public Beta.
+</Important>
+
+<CardGrid>
+  <Card
+    link="/usage-guide/introduction"
+    icon="mdi:lightbulb"
+    title="Usage Guide"
+  >
+    Get started with using Vrite
+  </Card>
+
+  <Card
+    link="/javascript-sdk/introduction"
+    icon="mdi:javascript"
+    title="JavaScript SDK"
+  >
+    Learn how to build with Vrite’s JavaScript SDK
+  </Card>
+
+  <Card
+    link="/api/introduction"
+    icon="mdi:api"
+    title="API Reference"
+  >
+    Reference for Vrite’s REST API
+  </Card>
+
+  <Card
+    link="/recipes/introduction"
+    icon="mdi:text-box-multiple"
+    title="Recipes"
+  >
+    Jump right into Vrite with ready recipes.
+  </Card>
+</CardGrid>

apps/docs/src/content/docs/self-hosting/configuration.md

@@ -1,6 +1,6 @@
 ---
-title: "Configuring Self-Hosted Vrite"
 slug: "self-hosting/configuration"
+title: "Configuring Self-Hosted Vrite"
 ---
 
 To properly host Vrite, you first have to configure a couple of environment variables. This guide aims to give you an overview of the available options.
@@ -50,13 +50,13 @@ For production, make sure to either secure and properly configure your MinIO ins
 
 ## GitHub OAuth2
 
-If you want to add _Sign in with GitHub_ option to your authentication page, make sure to provide the `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` variables. Follow [the official guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to acquire the values.
+If you want to add _Sign in with GitHub_ option to your authentication page, make sure to provide the `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` variables. Follow [the official guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to acquire the values. Use `{{PUBLIC_APP_URL}}/login/github/callback` for your **Authorization callback URL**.
 
 When the variables are not provided, the GitHub sign-in will be disabled.
 
 ## GitHub App
 
-To enable Git sync and synchronize your content from your GitHub repo, you’ll have to provide credentials for your GitHub App. To obtain them, follow [the official guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and then fill out the variables:
+To enable Git sync and synchronize your content from your GitHub repo, you’ll have to provide credentials for your GitHub App. To obtain them, follow [the official guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) (use `{{PUBLIC_APP_URL}}/github/callback` for your **Callback URL**) and then fill out the variables:
 
 ```
 # GitHub App (optional - GitHub Git sync)
@@ -90,4 +90,4 @@ To enable AI question-answering, you have to configure both Weaviate and OpenAI.
 
 The `OPENAI_API_KEY` will be automatically forwarded to your Weaviate instance to simplify the use of `text2vec-openai` vectorizer.
 
-When the variables are not provided, the AI question-answering feature will be disabled.
+When the variables are not provided, the AI question-answering feature will be disabled.

apps/docs/src/content/docs/self-hosting/docker.md

@@ -1,6 +1,6 @@
 ---
-title: "Self-Hosting Vrite with Docker"
 slug: "self-hosting/docker"
+title: "Self-Hosting Vrite with Docker"
 ---
 
 Vrite aims to provide the best and most accessible technical writing experience. To do so, we provide both a ready, [easy-to-use “Vrite Cloud” instance](https://app.vrite.io/), as well as an option for you to **self-host Vrite** on your own servers.
@@ -15,7 +15,6 @@ git clone https://github.com/vriteio/vrite
 cd vrite
 
 cp .env.example docker.env
-
 ```
 
 Then, open the `docker.env` file and fill in the environment variables. You can refer to the [Configuration](/self-hosting/configuration) section for more information on the available options.
@@ -24,7 +23,6 @@ When you’re done, you can start Vrite with:
 
 ```bash
 docker compose up
-
 ```
 
-> **Important!** Currently, when self-hosting, Vrite extensions aren’t available, as the Vrite Extension System isn’t ready yet. We’ll enable later on.
+> **Important!** Currently, when self-hosting, Vrite extensions aren’t available, as the Vrite Extension System isn’t ready yet. We’ll enable later on.

apps/docs/src/content/docs/usage-guide/content-editor.md

@@ -1,51 +1,44 @@
 ---
-title: "Writing in Vrite Editor"
 slug: "/usage-guide/content-editor"
+title: "Writing in Vrite Editor"
 ---
 
 The content editor is the core part of Vrite — this is where you can create your next technical masterpiece. And, thanks to all the features, formatting options, and content blocks Vrite supports - it should be a breeze!
 
 ## Editing Menus
 
-Editing menus are one of the most important parts of the Vrite editing experience. Implementing modern design and UX found in other state-of-the-art WYSIWYG editors, Vrite provides you with a set of easily-accessible menus that are right there when you need them!
+Editing menus are one of the most important parts of the Vrite editing experience. Implementing modern design and UX found in other state-of-the-art WYSIWYG editors, Vrite provides you with a set of easily-accessible menus that are right there when you need them.
 
 ### Bubble Menu
 
-![Bubble menu in Vrite editor](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/Op7dQICGLf8LK1fb-00mF.png)
+![Bubble menu in Vrite editor](https://assets.vrite.io/65256a9ef6d09e66c21a447d/g0ZLlh2KKmSzNEiZNYfXm.png?w=1000)
 
 Select some text for the bubble menu to appear. It's meant for inline formatting, inserting links, and comments.
 
 ### Block Menu
 
-![Block menu in Vrite editor](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/TfxcygyBCv25jW0r0UsD8.png)
+![Block menu in Vrite editor](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/TfxcygyBCv25jW0r0UsD8.png?w=1000)
 
 Used for inserting block content, like lists, headings, images, or code blocks. Can be triggered at the beginning of any new paragraph by typing `/` or clicking a button on the left of the paragraph. You can **filter the list** by typing queries right after the `/`, and move between items with **arrow keys**.
 
 ### Link Menu
 
-![Link menu in Vrite](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/HKLbwDEH97l6qjyhhQaEh.png)
+![](https://assets.vrite.io/65256a9ef6d09e66c21a447d/XgIE6BkCoWd3FK-u4d2KU.png?w=1000)
 
 Move the cursor into a linked text fragment to display a preview of the linked content.
 
 ## Inline formatting options
 
 The following inline formatting options are supported in the Vrite editor (on the side — where applicable — their respective Markdown and keyboard shortcuts):
 
-- **Bold** — `**markdown**` — `CTRL B`/`CMD B`;
-
-- **Italic** — `*markdown*` — `CTRL I`/`CMD I`;
-
-- **Strikethrough** — `~~markdown~~` — `CTRL SHIFT X`/`CMD SHIFT X`;
-
-- **Inline code** — `markdown` — `CTRL E`/`CMD E`;
-
-- **Highlight** — `==markdown==` — `CTRL SHIFT H`/`CMD SHIFT H`;
-
-- **Superscript** — `CTRL ,`/`CMD ,`;
-
-- **Subscript** — `CTRL .`/`CMD .`;
-
-- **Link** — `[markdown](link)` — you can also `CTRL V`/`CMD V` the URL to link the selected text fragment;
+- **Bold** — `**markdown**` — `Ctrl B`/`⌘B`;
+- **Italic** — `*markdown*` — `Ctrl I`/`⌘I`;
+- **Strikethrough** — `~~markdown~~` — `Ctrl Shift X`/`⌘ Shift X`;
+- **Inline code** — `markdown` — `Ctrl E`/`⌘E`;
+- **Highlight** — `==markdown==` — `Ctrl Shift H`/`⌘ Shift H`;
+- **Superscript** — `Ctrl ,`/`⌘,`;
+- **Subscript** — `Ctrl .`/`⌘.`;
+- **Link** — `[markdown](link)` — you can also `Ctrl V`/`⌘V` the URL to link the selected text fragment;
 
 ## Content blocks
 
@@ -54,101 +47,102 @@ Content blocks are large pieces of content, insertable from the block menu or wi
 ### Basic Content Blocks
 
 - **Headings** (up to 6 levels of nesting) — from `# markdown` to `###### markdown`;
-
 - **Blockquotes** — `> markdown`;
-
 - **Horizontal rule** — `--- `;
-
 - **Nestable Lists**:
-
   - **Ordered** — `1. markdown`;
-
   - **Unordered** — `- markdown`;
-
   - **Task-based** — `[x]` for checked or `[ ]` for unchecked item;
 
-### Special Content Blocks
+When inside a list, you can use `Tab` to inset a list (from 2nd item up) and `Shift Tab` to move out.
 
-![Vrite image block](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/4t_retydgKtPA8YhCULYd.png)
+### Element
 
-**Image** — lets you insert an image, either by uploading it directly to Vrite or referencing it through a URL. You can also set an alt text and drag and drop the block to change its position. For larger images, you can resize the preview to take up less space.
+![Vrite content editor - element block](https://assets.vrite.io/65256a9ef6d09e66c21a447d/gNilK5WKjI9-lsk7FqtYR.png?w=1000)
 
-![Vrite embed block](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/0OxiNuaXHPy0sGNuJSsKq.png)
+Lets you insert custom markup right into content using JSX/XML-like syntax. The elements can be self-closing (opening tag ending with `/>`) or contain content (opening tag ending with `>`).
 
-**Embed** — lets you embed content from supported platforms. You can provide any link or ID and Vrite will generate a proper preview. You can also drag and drop the block to change its position. Supported embeds are:
+All attributes/props are transformed into structured JSON content.
 
-- **CodePen**
+### Image
 
-- **CodeSandbox**
+![Vrite content editor - image block](https://assets.vrite.io/65256a9ef6d09e66c21a447d/8Dyvp53XvKde4o8wMzmoB.png?w=1000)
+
+Lets you insert an image, either by uploading it directly to Vrite or referencing it through a URL. You can also set an alt text, by switching to _Alt_ input. For larger images, you can resize the preview to take up less space by dragging the bottom-right handle.
+
+### Embed
 
+![Vrite content editor - embed block](https://assets.vrite.io/65256a9ef6d09e66c21a447d/o-RukHa_MXmBa-yGkUbPI.png?w=1000)
+
+Lets you embed content from supported platforms. You can provide any link or ID and Vrite will generate a proper preview. Supported embeds are:
+
+- **CodePen**
+- **CodeSandbox**
 - **YouTube**
 
+### Table
+
 ![Table in Vrite](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/CThF1-P0HI4iWTIWlvQ0s.png)
 
-**Table** — lets you include and edit tabular data in your content. When you move your cursor inside the table, a special menu will appear on the bottom, with the following options (from left to right):
+Lets you include and edit tabular data in your content. When you move your cursor inside the table, a special menu will appear on the bottom, with the following options (from left to right):
 
 - Insert row above
-
 - Insert row below
-
 - Insert column left
-
 - Insert column right
-
 - Add/remove header
-
 - Delete table
 
 You can also select individual cells by either tripple-clicking them, or holding and dragging through the table. Depending on the selection, the menu can contain a subset of the following options:
 
 - Merge cells
-
 - Split cell
-
 - Delete column(s)
-
 - Delete row(s)
-
 - Delete table
 
-![Vrite code block](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/NLQ2piOpD-6jOZEtv67gT.png)
+### Code block
+
+![Vrite content editor - code block](https://assets.vrite.io/65256a9ef6d09e66c21a447d/SR1f0Nh3uhnifDOEUMAIY.png?w=1000)
 
-**Code block** — a full-featured VS-Code-like [Monaco editor](https://microsoft.github.io/monaco-editor/) for editing your code snippets. It supports syntax highlighting for the vast majority of popular languages and full autocomplete for some, like JavaScript/TypeScript, CSS, and HTML. You can select the code language using the input with autocomplete menu and, whenever possible, format the code using the built-in [Prettier integration](https://prettier.io/).
+A full-featured VS-Code-like [Monaco editor](https://microsoft.github.io/monaco-editor/) for editing your code snippets. It supports syntax highlighting for the vast majority of popular languages and full autocomplete for some, like JavaScript/TypeScript, CSS, and HTML.
+
+You can select the code language using the input with autocomplete menu and, whenever possible, format the code using the built-in [Prettier integration](https://prettier.io/).
+
+You can also assign additional metadata to the snippet, like title (by switching to the _Title_ input) and other metadata in the _Language_ input, separated by `Space` from the language indentifier.
 
 ## Editor Toolbar
 
 ![Vrite editor toolbar](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/Nm-ODaVo67yulTH5BhpQx.png)
 
-In addition to all the features available from the main editing view, the Vrite editor also provides a toolbar with a few more options:
+In addition to all the features available from the main editing view, the Vrite editor also has a toolbar with a few more options:
 
 - _Content Stats_ — opens a dropdown with detailed statistics about your content, like the number of words or Lines of Code (LOCs) written;
-
-- _Export_ — allows you to “Export” the content to the underlying JSON format, HTML, or GitHub-Flavored Markdown (GFM) for easy download or copy-paste;
-
-- _Zen mode_ — allows you to focus solely on your content, hiding all the distractions and centering the content editor; You can easily go back by clicking the button in the top-right corner or using `ESC` key;
+- _Export_ — allows you to “Export” the content to the underlying structured JSON format, HTML, or GitHub-Flavored Markdown (GFM) for easy download or copy-paste; Fragments of content that aren’t supported by the given format will be omitted.
+- _Zen mode_ — allows you to focus solely on your content, hiding all the distractions and centering the content editor; You can easily go back by clicking the button in the top-right corner or using `Esc` key;
 
 The _Export_ functions opens a modal presenting the output and options to _Download_ or _Copy_ it easily:
 
-![Vrite editor export modal](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/Ti3gDzFHWvSRgu0X4UgS7.png)
+![Vrite content editor - export modal](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/Ti3gDzFHWvSRgu0X4UgS7.png)
 
 ## Real-Time Collaboration
 
-Vrite editor supports real-time collaboration, displaying not only the team members currently viewing/editing the piece, but also their current selection. In case of uncertainty, you can hover right over the cursor or the badge in the toolbar to view the username.
+Vrite supports real-time collaboration, displaying not only the team members currently viewing/editing the piece, but also their current selection. In case of uncertainty, you can hover right over the cursor or the badge in the toolbar to view the username.
 
 ![Real-time collaboration in Vrite editor](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/RaOXP4MkcZZpEWJHQ3cAd.png)
 
 ### Commenting
 
-You can use Vrite’s comments and threads to discuss specific pieces of content right within the editor. To do so, select a piece of text and choose _Comment_ from the bubble menu. You’ll see the thread and all of related comments on the right side of your content, while your cursor is within the commented fragment.
+You can use comment threads to discuss specific pieces of content right within the editor. To do so, select a piece of text and choose _Comment_ from the bubble menu. You’ll see the thread and all of related comments on the right side of your content, while your cursor is within the commented fragment.
 
 In comments, you can use all inline formatting options that are also available in the editor, through Markdown and keyboard shortcuts. Once the discussion is done, you can mark the comment thread as _Resolved_ using the button in the top-right corner.
 
-![](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/hi3iXvouSZUg1TYpgKhsY.png)
+![Vrite content editor - comment thread](https://assets.vrite.io/65256a9ef6d09e66c21a447d/zNsilpN7A87SmG7WpAyqz.png)
 
 ## Block Actions
 
 Block Actions are special actions provided by Vrite Extensions for various top-level blocks, like images, embeds, or paragraphs, that can process and change the content of the given block. A good example of this is the **GPT-3.5** extension, which can insert new content, generated by OpenAI’s LLM or entirely edit the given paragraph.
 
 ![GPT-3.5 extension's block action](https://assets.vrite.io/6409e82d7dfc74cef7a72e0d/ytq0welaqPIu7XkycI0cv.png)
 
-You can read more about Vrite Extensions [here](/vrite-extensions).
+You can read more about Vrite Extensions [here](/usage-guide/vrite-extensions/).