docs/usage: simplify

Signed-off-by: Akihiro Suda <[email protected]>

Author: AkihiroSuda

website/content/en/docs/Config/_index.md

@@ -4,3 +4,11 @@ weight: 5
 ---
 
 For all the configuration items, see <https://github.com/lima-vm/lima/blob/master/examples/default.yaml>.
+
+The current default spec:
+- OS: Ubuntu
+- CPU: 4 cores
+- Memory: 4 GiB
+- Disk: 100 GiB
+- Mounts: `~` (read-only), `/tmp/lima` (writable)
+- SSH: 127.0.0.1:60022

website/content/en/docs/Usage/_index.md

@@ -3,11 +3,10 @@ title: Usage
 weight: 2
 ---
 
-## Start a linux instance
+## Starting a Linux instance
 
-```console
-limactl start [--name=NAME] [--tty=false] <template://TEMPLATE>
-```
+Run `limactl start <INSTANCE>` to create and start the first instance.
+The `<INSTANCE>` name defaults to "default".
 
 ```console
 $ limactl start
@@ -24,38 +23,34 @@ Choose `Proceed with the current configuration`, and wait until "READY" to be pr
 
 For automation,  `--tty=false` flag can be used for disabling the interactive user interface.
 
-### Advanced usage
+### Customization
 To create an instance "default" from a template "docker":
-```console
-$ limactl start --name=default template://docker
+```bash
+limactl create --name=default template://docker
+limactl start default
 ```
 
-To create an instance "default" with modified parameters:
-```console
-$ limactl start --set='.cpus = 2 | .memory = "2GiB"'
-```
+See also the command reference:
+- [`limactl create`](../reference/limactl_create/)
+- [`limactl start`](../reference/limactl_start/)
+- [`limactl edit`](../reference/limactl_edit/)
 
-To see the template list:
-```console
-$ limactl start --list-templates
+### Executing Linux commands
+Run `limactl shell <INSTANCE> <COMMAND>` to launch `<COMMAND>` on the VM:
+```bash
+limactl shell default uname -a
 ```
 
-To create an instance "default" from a local file:
-```console
-$ limactl start --name=default /usr/local/share/lima/templates/fedora.yaml
-```
-
-To create an instance "default" from a remote URL (use carefully, with a trustable source):
-```console
-$ limactl start --name=default https://raw.githubusercontent.com/lima-vm/lima/master/examples/alpine.yaml
-```
-
-#### limactl shell
-`limactl shell <INSTANCE> <COMMAND>`: launch `<COMMAND>` on Linux.
+See also the command reference:
+- [`limactl shell`](../reference/limactl_shell/)
 
 For the "default" instance, this command can be shortened as `lima <COMMAND>`.
+```bash
+lima uname -a
+```
 The `lima` command also accepts the instance name as the environment variable `$LIMA_INSTANCE`.
 
+
 SSH can be used too:
 ```console
 $ limactl ls --format='{{.SSHConfigFile}}' default
@@ -64,28 +59,6 @@ $ limactl ls --format='{{.SSHConfigFile}}' default
 $ ssh -F /Users/example/.lima/default/ssh.config lima-default
 ```
 
-#### limactl completion
+### Shell completion
 - To enable bash completion, add `source <(limactl completion bash)` to `~/.bash_profile`.
-
 - To enable zsh completion, see `limactl completion zsh --help`
-
-## Configuration
-{{% fixlinks %}}
-
-See [`./examples/default.yaml`](./examples/default.yaml).
-
-The current default spec:
-- OS: Ubuntu 23.04 (Lunar Lobster)
-- CPU: 4 cores
-- Memory: 4 GiB
-- Disk: 100 GiB
-- Mounts: `~` (read-only), `/tmp/lima` (writable)
-- SSH: 127.0.0.1:60022
-
-## How it works
-
-- Hypervisor: [QEMU with HVF accelerator (default), or Virtualization.framework](./docs/vmtype.md)
-- Filesystem sharing: [Reverse SSHFS (default),  or virtio-9p-pci aka virtfs, or virtiofs](./docs/mount.md)
-- Port forwarding: `ssh -L`, automated by watching `/proc/net/tcp` and `iptables` events in the guest
-
-{{% /fixlinks %}}

website/content/en/docs/faq/_index.md

@@ -7,34 +7,42 @@ weight: 6
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
 - [Generic](#generic)
-    - ["What's my login password?"](#whats-my-login-password)
-    - ["Does Lima work on ARM Mac?"](#does-lima-work-on-arm-mac)
-    - ["Can I run non-Ubuntu guests?"](#can-i-run-non-ubuntu-guests)
-    - ["Can I run other container engines such as Docker and Podman? What about Kubernetes?"](#can-i-run-other-container-engines-such-as-docker-and-podman-what-about-kubernetes)
-    - ["Can I run Lima with a remote Linux machine?"](#can-i-run-lima-with-a-remote-linux-machine)
-    - ["Advantages compared to Docker for Mac?"](#advantages-compared-to-docker-for-mac)
+  - ["How does Lima work?"](#how-does-lima-work)
+  - ["What's my login password?"](#whats-my-login-password)
+  - ["Does Lima work on ARM Mac?"](#does-lima-work-on-arm-mac)
+  - ["Can I run non-Ubuntu guests?"](#can-i-run-non-ubuntu-guests)
+  - ["Can I run other container engines such as Docker and Podman? What about Kubernetes?"](#can-i-run-other-container-engines-such-as-docker-and-podman-what-about-kubernetes)
+  - ["Can I run Lima with a remote Linux machine?"](#can-i-run-lima-with-a-remote-linux-machine)
+  - ["Advantages compared to Docker for Mac?"](#advantages-compared-to-docker-for-mac)
 - [QEMU](#qemu)
-    - ["QEMU crashes with `HV_ERROR`"](#qemu-crashes-with-hv_error)
-    - ["QEMU is slow"](#qemu-is-slow)
-    - [error "killed -9"](#error-killed--9)
-    - ["QEMU crashes with `vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed`"](#qemu-crashes-with-vmx_write_mem-mmu_gva_to_gpa-xxxxxxxxxxxxxxxx-failed)
+  - ["QEMU crashes with `HV_ERROR`"](#qemu-crashes-with-hv_error)
+  - ["QEMU is slow"](#qemu-is-slow)
+  - [error "killed -9"](#error-killed--9)
+  - ["QEMU crashes with `vmx_write_mem: mmu_gva_to_gpa XXXXXXXXXXXXXXXX failed`"](#qemu-crashes-with-vmx_write_mem-mmu_gva_to_gpa-xxxxxxxxxxxxxxxx-failed)
 - [VZ](#vz)
-    - ["Lima gets stuck at `Installing rosetta...`"](#lima-gets-stuck-at-installing-rosetta)
+  - ["Lima gets stuck at `Installing rosetta...`"](#lima-gets-stuck-at-installing-rosetta)
 - [Networking](#networking)
-    - ["Cannot access the guest IP 192.168.5.15 from the host"](#cannot-access-the-guest-ip-192168515-from-the-host)
-    - ["Ping shows duplicate packets and massive response times"](#ping-shows-duplicate-packets-and-massive-response-times)
-    - ["IP address is not assigined for vmnet networks"](#ip-address-is-not-assigined-for-vmnet-networks)
+  - ["Cannot access the guest IP 192.168.5.15 from the host"](#cannot-access-the-guest-ip-192168515-from-the-host)
+  - ["Ping shows duplicate packets and massive response times"](#ping-shows-duplicate-packets-and-massive-response-times)
+  - ["IP address is not assigined for vmnet networks"](#ip-address-is-not-assigined-for-vmnet-networks)
 - [Filesystem sharing](#filesystem-sharing)
-    - ["Filesystem is slow"](#filesystem-is-slow)
-    - ["Filesystem is not writable"](#filesystem-is-not-writable)
+  - ["Filesystem is slow"](#filesystem-is-slow)
+  - ["Filesystem is not writable"](#filesystem-is-not-writable)
 - [External projects](#external-projects)
-    - ["I am using Rancher Desktop. How to deal with the underlying Lima?"](#i-am-using-rancher-desktop-how-to-deal-with-the-underlying-lima)
+  - ["I am using Rancher Desktop. How to deal with the underlying Lima?"](#i-am-using-rancher-desktop-how-to-deal-with-the-underlying-lima)
 - ["Hints for debugging other problems?"](#hints-for-debugging-other-problems)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ### Generic
+#### "How does Lima work?"
+
+- Hypervisor: [QEMU with HVF accelerator (default), or Virtualization.framework](../config/vmtype/)
+- Filesystem sharing: [Reverse SSHFS (default),  or virtio-9p-pci aka virtfs, or virtiofs](../config/mount/)
+- Port forwarding: `ssh -L`, automated by watching `/proc/net/tcp` and `iptables` events in the guest
+
 #### "What's my login password?"
 Password is disabled and locked by default.
 You have to use `limactl shell bash` (or `lima bash`) to open a shell.
@@ -213,4 +221,4 @@ If you need to create an `override.yaml` file, its location should be:
     - `$HOME/.lima/<INSTANCE>/serial.log`
     - `/var/log/cloud-init-output.log` (inside the guest)
     - `/var/log/cloud-init.log` (inside the guest)
-- Make sure that you aren't mixing up tabs and spaces in the YAML.
+- Make sure that you aren't mixing up tabs and spaces in the YAML.