docs: split long pages, fix minor errors, etc.

website/content/en/docs/config/environment-variables.md

@@ -109,18 +109,18 @@ This page documents the environment variables used in Lima.
 ### `LIMA_SSH_PORT_FORWARDER`
 
 - **Description**: Specifies to use the SSH port forwarder (slow) instead of gRPC (fast, previously unstable)
-- **Default**: `false` (since v1.1.0-beta.0)
+- **Default**: `false` (since v1.1.0)
 - **Usage**: 
   ```sh
   export LIMA_SSH_PORT_FORWARDER=false
   ```
 - **The history of the default value**:
-  | Version       | Default value       |
-  |---------------|---------------------|
-  | v0.1.0        | `true`, effectively |
-  | v1.0.0        | `false`             |
-  | v1.0.1        | `true`              |
-  | v1.1.0-beta.0 | `false`             |
+  | Version | Default value       |
+  |---------|---------------------|
+  | v0.1.0  | `true`, effectively |
+  | v1.0.0  | `false`             |
+  | v1.0.1  | `true`              |
+  | v1.1.0  | `false`             |
 
 ### `LIMA_USERNET_RESOLVE_IP_ADDRESS_TIMEOUT`
 

website/content/en/docs/config/multi-arch.md

@@ -3,7 +3,7 @@ title: Intel-on-ARM and ARM-on-Intel
 weight: 20
 ---
 
-Lima supports two modes for running Intel-on-ARM and ARM-on-Intel:
+Lima supports several modes for running Intel-on-ARM and ARM-on-Intel:
 - [Slow mode](#slow-mode)
 - [Fast mode](#fast-mode)
 - [Fast mode 2](#fast-mode-2)

website/content/en/docs/config/plugin/_index.md

@@ -0,0 +1,4 @@
+---
+title: Plug-in
+weight: 90
+---

website/content/en/docs/config/plugin/cli.md

@@ -0,0 +1,60 @@
+---
+title: CLI plugins
+weight: 2
+---
+
+ | ⚡ Requirement | Lima >= 2.0 |
+ |----------------|-------------|
+
+Lima supports a plugin-like command aliasing system similar to `git`, `kubectl`, and `docker`. When you run a `limactl` command that doesn't exist, Lima will automatically look for an external program named `limactl-<command>` in your system's PATH.
+
+## Creating Custom Aliases
+
+To create a custom alias, create an executable script with the name `limactl-<alias>` and place it somewhere in your PATH.
+
+**Example: Creating a `ps` alias for listing instances**
+
+1. Create a script called `limactl-ps`:
+   ```bash
+   #!/bin/sh
+   # Show instances in a compact format
+   limactl list --format table "$@"
+   ```
+
+2. Make it executable and place it in your PATH:
+   ```bash
+   chmod +x limactl-ps
+   sudo mv limactl-ps /usr/local/bin/
+   ```
+
+3. Now you can use it:
+   ```bash
+   limactl ps                    # Shows instances in table format
+   limactl ps --quiet            # Shows only instance names
+   ```
+
+**Example: Creating an `sh` alias**
+
+```bash
+#!/bin/sh
+# limactl-sh - Connect to an instance shell
+limactl shell "$@"
+```
+
+After creating this alias:
+```bash
+limactl sh default           # Equivalent to: limactl shell default
+limactl sh myinstance bash   # Equivalent to: limactl shell myinstance bash
+```
+
+## How It Works
+
+1. When you run `limactl <unknown-command>`, Lima first tries to find a built-in command
+2. If no built-in command is found, Lima searches for `limactl-<unknown-command>` in your PATH
+3. If found, Lima executes the external program and passes all remaining arguments to it
+4. If not found, Lima shows the standard "unknown command" error
+
+This system allows you to:
+- Create personal shortcuts and aliases
+- Extend Lima's functionality without modifying the core application
+- Share custom commands with your team by distributing scripts

website/content/en/docs/config/plugin/vm.md

@@ -0,0 +1,7 @@
+---
+title: VM driver plugins
+weight: 1
+---
+
+See [Virtual Machine Drivers](../../dev/drivers.md).
+<!-- TODO: migrate the most of the content from ../../dev/drivers.md to here -->

website/content/en/docs/config/port.md

@@ -11,12 +11,12 @@ Lima supports two port forwarders: SSH and GRPC.
 
 The default port forwarder is shown in the following table.
 
-| Version       | Default |
-| ------------- | ------- |
-| v0.1.0        | SSH     |
-| v1.0.0        | GRPC    |
-| v1.0.1        | SSH     |
-| v1.1.0-beta.0 | GRPC    |
+| Version | Default |
+| --------| ------- |
+| v0.1.0  | SSH     |
+| v1.0.0  | GRPC    |
+| v1.0.1  | SSH     |
+| v1.1.0  | GRPC    |
 
 The default was once changed to GRPC in Lima v1.0, but it was reverted to SSH in v1.0.1 due to stability reasons.
 The default was further reverted to GRPC in Lima v1.1, as the stability issues were resolved.

website/content/en/docs/config/vmtype/_index.md

@@ -0,0 +1,28 @@
+---
+title: VM types
+weight: 10
+---
+
+Lima supports several VM drivers for running guest machines:
+
+The vmType can be specified only on creating the instance.
+The vmType of existing instances cannot be changed.
+
+> **💡 For developers**: See [Virtual Machine Drivers](../../dev/drivers) for technical details about driver architecture and creating custom drivers.
+
+
+See the following flowchart to choose the best vmType for you:
+```mermaid
+flowchart
+  host{"Host OS"} -- "Windows" --> wsl2["WSL2"]
+  host -- "Linux" --> qemu["QEMU"]
+  host -- "macOS" --> intel_on_arm{"Need to run <br> Intel binaries <br> on ARM?"}
+  intel_on_arm -- "Yes" --> just_elf{"Just need to <br> run Intel userspace (fast), <br> or entire Intel VM (slow)?"}
+  just_elf -- "Userspace (fast)" --> vz
+  just_elf -- "VM (slow)" --> qemu
+  intel_on_arm --  "No" --> vz["VZ"]
+```
+
+The default vmType is QEMU in Lima prior to v1.0.
+Starting with Lima v1.0, Lima will use VZ by default on macOS (>= 13.5) for new instances,
+unless the config is incompatible with VZ. (e.g., legacyBIOS or 9p is enabled)

website/content/en/docs/config/vmtype/qemu.md

@@ -0,0 +1,10 @@
+---
+title: QEMU
+weight: 1
+---
+
+"qemu" option makes use of QEMU to run guest operating system.
+
+Recommended QEMU version:
+- v8.2.1 or later (macOS)
+- v6.2.0 or later (Linux)

website/content/en/docs/config/vmtype/vz.md

@@ -0,0 +1,42 @@
+---
+title: VZ
+weight: 2
+---
+
+| ⚡ Requirement | Lima >= 0.14, macOS >= 13.0 |
+|-------------------|-----------------------------|
+
+"vz" option makes use of native virtualization support provided by macOS Virtualization.Framework.
+
+An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=vz
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
+```yaml
+# Example to run ubuntu using vmType: vz instead of qemu (Default)
+vmType: "vz"
+images:
+- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img"
+  arch: "x86_64"
+- location: "https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-arm64.img"
+  arch: "aarch64"
+mounts:
+  - location: "~"
+```
+{{% /tab %}}
+{{< /tabpane >}}
+### Caveats
+- "vz" option is only supported on macOS 13 or above
+- Virtualization.framework doesn't support running "intel guest on arm" and vice versa
+
+### Known Issues
+- "vz" doesn't support `legacyBIOS: true` option, so guest machine like `centos-stream` and `oraclelinux-8` will not work on Intel Mac.
+- When running lima using "vz", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
+- On Intel Mac with macOS prior to 13.5, Linux kernel v6.2 (used by Ubuntu 23.04, Fedora 38, etc.) is known to be unbootable on vz.
+  kernel v6.3 and later should boot, as long as it is booted via GRUB.
+  https://github.com/lima-vm/lima/issues/1577#issuecomment-1565625668
+  The issue is fixed in macOS 13.5.

website/content/en/docs/config/vmtype/wsl2.md

@@ -0,0 +1,45 @@
+---
+title: WSL2
+weight: 3
+---
+
+> **Warning**
+> "wsl2" mode is experimental
+
+| ⚡ Requirement | Lima >= 0.18 + (Windows >= 10 Build 19041 OR Windows 11) |
+| ----------------- | -------------------------------------------------------- |
+
+"wsl2" option makes use of native virtualization support provided by Windows' `wsl.exe` ([more info](https://learn.microsoft.com/en-us/windows/wsl/about)).
+
+An example configuration:
+{{< tabpane text=true >}}
+{{% tab header="CLI" %}}
+```bash
+limactl start --vm-type=wsl2 --mount-type=wsl2 --containerd=system
+```
+{{% /tab %}}
+{{% tab header="YAML" %}}
+```yaml
+# Example to run Fedora using vmType: wsl2
+vmType: wsl2
+images:
+# Source: https://github.com/runfinch/finch-core/blob/main/Dockerfile
+- location: "https://deps.runfinch.com/common/x86-64/finch-rootfs-production-amd64-1690920103.tar.zst"
+  arch: "x86_64"
+  digest: "sha256:53f2e329b8da0f6a25e025d1f6cc262ae228402ba615ad095739b2f0ec6babc9"
+mountType: wsl2
+containerd:
+  system: true
+  user: false
+```
+{{% /tab %}}
+{{< /tabpane >}}
+
+### Caveats
+- "wsl2" option is only supported on newer versions of Windows (roughly anything since 2019)
+
+### Known Issues
+- "wsl2" currently doesn't support many of Lima's options. See [this file](https://github.com/lima-vm/lima/blob/master/pkg/wsl2/wsl_driver_windows.go#L19) for the latest supported options.
+- When running lima using "wsl2", `${LIMA_HOME}/<INSTANCE>/serial.log` will not contain kernel boot logs
+- WSL2 requires a `tar` formatted rootfs archive instead of a VM image
+- Windows doesn't ship with ssh.exe, gzip.exe, etc. which are used by Lima at various points. The easiest way around this is to run `winget install -e --id Git.MinGit` (winget is now built in to Windows as well), and add the resulting `C:\Program Files\Git\usr\bin\` directory to your path.