Skip to content

Commit

Permalink
docs: add content translator v1.3 guide
Browse files Browse the repository at this point in the history
  • Loading branch information
johannschopplich committed Jun 17, 2024
1 parent 02f7e99 commit e1859fd
Show file tree
Hide file tree
Showing 4 changed files with 55 additions and 56 deletions.
89 changes: 34 additions & 55 deletions content/1.docs/1.live-preview/1.index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,70 +7,35 @@ description: Learn how to install and configure Kirby Live Preview in your Kirby

### Step 1: Install the Plugin

#### Download
Although it is a commercial plugin, you can download and test the plugin in your local environment before purchasing it.

After your purchase, you will receive a download link for the Kirby Live Preview plugin. Download the ZIP file and extract it to your `site/plugins` folder. It should look like this:
#### Composer

```
site/plugins/
├─ kirby-live-preview/
│ └─ … All plugin files
```
The recommended way to install the plugin is via Composer. To install the plugin, run the following command in your terminal:

#### Composer :u-badge{label="v1.2.1+" class="align-middle ml-2 !rounded-full" variant="subtle"}

The recommended way to install the plugin is via Composer. Since it is not available through Packagist, you will need to connect to our private repository [repo.kirby.tools](https://repo.kirby.tools) and authenticate your package download. Authentication is done via a license code that you can get from the [Kirby Tools Hub](https://hub.kirby.tools) after your purchase.

:prose-video{src="/vid/kirby-tools-hub-license.mp4" poster="/vid/kirby-tools-hub-license-poster.jpg" width="908" height="540"}

To get access to the private repository and enable Composer installs, follow these steps:

1. Go to [hub.kirby.tools](https://hub.kirby.tools). Log in with the email you used for the purchase and the order number.
2. After successful login, a license code will be displayed next to the Composer repository configuration and a CLI command.
3. Copy and paste the Composer configuration into your `composer.json` file. This will enable Composer to resolve our plugins. Your `composer.json` file should include this repository item:
```json [composer.json]
{
"repositories": [
{
"type": "composer",
"url": "https://repo.kirby.tools"
}
]
}
```
4. Copy and run the Composer CLI command, which will generate an `auth.json` file for you, a Composer standard for authenticating against private repositories. Composer will send your license key (or license keys if you have purchased multiple plugins) as a bearer token with each request to `repo.kirby.tools`. As an alternative to running the command, you can create the file yourself. An `auth.json` file should look like this:
```json [auth.json]
{
"bearer": {
"repo.kirby.tools": "KT1-gd9Ymx30rM-ylZ3h6yF3l"
}
}
```

To install multiple plugins in one Kirby project, add all required license codes to your local `auth.json` file. Separate each license code with a comma, e.g:

```json [auth.json]
{
"bearer": {
"repo.kirby.tools": "KT1-A, KT1-B"
}
}
```bash
composer require johannschopplich/kirby-live-preview
```

::callout{icon="i-ri-information-line"}
The license code is unique to your purchase and should be kept private. We recommend to exclude it from version control by adding it to your `.gitignore` file.
::
Prior to v1.3, the plugin was published on a private Composer repository. It is now available on Packagist and can be installed without authentication. Your license key remains the same and is still required in production environments. To migrate your license key to the new location, follow these steps:

The Kirby Tools Composer repository is now set up. You can install the plugin by running the following command in your terminal:
- Open a Panel page that contains the Live Preview section.
- Your license key is **is automatically migrated** from the `auth.json` file in your root directory to the new location in the `/site/config/.kirby-tools-licenses` file.
- Update your `.gitignore` file to exclude the new license file.

```bash
composer require johannschopplich/kirby-live-preview
```
You can remove the `repo.kirby.tools` repository configuration from your `composer.json` file.

Last but not least, you can manage Kirby Live Preview like any other plugin, for example, download updates:
::

#### Download

Head over to the [releases page](https://github.com/kirby-tools/kirby-live-preview/releases) and download the latest version of the plugin as a ZIP file. Extract the contents of this ZIP file to your `site/plugins` folder. It should look like this:

```bash
composer update
```
site/plugins/
├─ kirby-live-preview/
│ └─ … All plugin files
```

### Step 2: Blueprint Setup
Expand All @@ -83,7 +48,7 @@ sections:
type: preview
```
### Step 3: Enjoy Real-Time Previews
### Step 3: Customize the Live Preview
Fit the Live Preview section to your blueprint layout and customize it to your needs: It can be part of any column and can even be sticky. The latter is useful for previewing content changes side-by-side with blocks or other fields:
Expand All @@ -110,6 +75,20 @@ Try navigating through the preview – if you click on a site link, such as in t
For mor configuration options, see the [Configuration](/docs/live-preview/configuration) guide.
### Step 4: Buy a License
You can test the plugin locally. However, you need to purchase a license to use the plugin in production environments.
Visit the [product page on Lemon Squeezy](https://byjohann.lemonsqueezy.com/buy/359409ce-840d-48c4-aca3-e7d79a95f6d4) and purchase a license. Then, open any Panel page that contains the Live Preview section. Click the **Activate** link to open the activation form:
:prose-video{src="/vid/kirby-live-preview-activation.mp4" poster="/vid/kirby-live-preview-activation-poster.jpg" width="908" height="540"}
Enter the email you used for the purchase and the order number and hit the submit button. Done! Thanks for supporting our work. Once you activate your license, the license activation buttons will disappear.
::callout{icon="i-ri-information-line"}
Your license key will be automatically stored in the `/site/config/.kirby-tools-licenses` file. Make sure to add this file to your `.gitignore` file to keep your license key private.
::

## Troubleshooting

### Live Preview in Safari
Expand Down
22 changes: 21 additions & 1 deletion content/1.docs/1.live-preview/4.changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,27 @@ You can then download the latest version from your [order page](https://app.lemo

## What's New?

### v1.2.4 :u-badge{label="Latest" class="align-middle ml-2 !rounded-full" variant="subtle"}
### v1.3.0 :u-badge{label="Latest" class="align-middle ml-2 !rounded-full" variant="subtle"}

Released on June 18, 2024.

**🚀 Features**

- New license management that allows activating licenses directly in the Panel.
- Deprecated the private Composer repository in favor of Packagist.

::callout{icon="i-ri-information-line"}
Prior to v1.3, the plugin was published on a private Composer repository. It is now available on Packagist and can be installed without authentication. Your license key remains the same and is still required in production environments. To migrate your license key to the new location, follow these steps:

- Open a Panel page that contains the Live Preview section.
- Your license key is **is automatically migrated** from the `auth.json` file in your root directory to the new location in the `/site/config/.kirby-tools-licenses` file.
- Update your `.gitignore` file to exclude the new license file.

You can remove the `repo.kirby.tools` repository configuration from your `composer.json` file.

::

### v1.2.4

Released on May 20, 2024.

Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added public/vid/kirby-live-preview-activation.mp4
Binary file not shown.

0 comments on commit e1859fd

Please sign in to comment.