Optimized en & zh docs

docs/10-mirror/01-mirror.md

@@ -8,15 +8,35 @@ title: "Mirror Command"
 
 Use following command to mirror multiple images between image registry servers parallelly:
 
-```bash
-hangar mirror \
-    --file=IMAGE_LIST.txt \
-    --source=[SOURCE_REGISTRY_URL] \
-    --destination=[DESTINATION_REGISTRY_URL] \
-    --arch=amd64,arm64 \
-    --os=linux \
-    --jobs=4
-```
+1. Prepare an example image list file.
+
+    ```txt title="example_image_list.txt"
+    cnrancher/hangar:latest
+    cnrancher/hangar:v1.7.0
+    # Add more images here...
+    ```
+
+    > Hangar `mirror` command supports two kinds of image list file formats, the image list file in this example is in `default` format. See [Image List Formats](image-list-format) for image list format specification.
+
+1. Run following command to mirror **amd64 & arm64, linux** container images by image list file from *SOURCE REGISTRY* to *DESTINATION REGISTRY* parallelly.
+
+    ```bash
+    #!/bin/bash
+
+    hangar mirror \
+        --file="example_image_list.txt" \
+        --source=SOURCE_REGISTRY_URL \
+        --destination=DESTINATION_REGISTRY_URL \
+        --arch=amd64,arm64 \
+        --os=linux \
+        --jobs=4
+    ```
+
+1. Use [inspect](../advanced-usage/inspect) command to view the copitd image manifest.
+
+    ```bash
+    hangar inspect --raw docker://DESTINATION_REGISTRY_URL/cnrancher/hangar:latest
+    ```
 
 ## Image List Format
 

docs/10-mirror/02-validate.md

@@ -9,10 +9,12 @@ The `hangar mirror validate` command (subcommand of `hangar mirror`) is used for
 Verify the mirrored images according to image list file after executing the [mirror](mirror#quick-start) command:
 
 ```bash
+#!/bin/bash
+
 hangar mirror validate \
-    --file=example_image_list.txt \
-    --source=[SOURCE_REGISTRY_URL] \
-    --destination=[DESTINATION_REGISTRY_URL] \
+    --file="example_image_list.txt" \
+    --source=SOURCE_REGISTRY_URL \
+    --destination=DESTINATION_REGISTRY_URL \
     --arch=amd64,arm64 \
     --os=linux \
     --jobs=4

docs/11-save/01-save.md

@@ -19,17 +19,27 @@ Use following command to save multiple container images from registry server int
 2. Save images from `docker.io` registry server into local archive file:
 
     ```bash
+    #!/bin/bash
+
     hangar save \
-        --file example_image_list.txt \
-        --source=docker.io \
-        --destination=save_example.zip \
+        --file="example_image_list.txt" \
+        --source="docker.io" \
+        --destination="save_example.zip" \
         --arch=amd64,arm64 \
         --os=linux \
         --jobs=4
     ```
 
     The images will saved into `saved_example.zip`.
 
+## Archive File
+
+Hangar uses the `zip` format archive file since version `v1.7.0`.
+
+**It should be noted that archive file created by older versions of hangar (`tar.gz`) are not compatible with new versions.**
+
+For more information about hangar archive usage, see [load](../load/load) and [archive](archive) page.
+
 ## Usage
 
 ```txt title="hangar save --help"
@@ -70,11 +80,3 @@ Global Flags:
 
 Use "hangar save [command] --help" for more information about a command.
 ```
-
-## Archive File
-
-Hangar uses the `zip` format archive file since version `v1.7.0`.
-
-**It should be noted that archive file created by older versions of hangar (`tar.gz`) are not compatible with new versions.**
-
-For more information about hangar archive usage, see [load](../load/load) and [archive](archive) page.

docs/11-save/02-validate.md

@@ -9,10 +9,12 @@ The `hangar save validate` command (subcommand of `hangar save`) is used for ens
 Verify the saved images according to image list file after executing the [save](save#quick-start) command:
 
 ```bash
+#!/bin/bash
+
 hangar save validate \
-    --file example_image_list.txt \
-    --source=docker.io \
-    --destination=save_example.zip \
+    --file="example_image_list.txt" \
+    --source="docker.io" \
+    --destination="save_example.zip" \
     --arch=amd64,arm64 \
     --os=linux \
     --jobs=4

docs/12-load/01-load.md

@@ -10,15 +10,23 @@ and the `load` command can be used in Air-Gapped (offline) installation scenario
 Use following command to load multiple container images from archive file created by [save](../save/save#quick-start) command to the *destination registry server* parallelly.
 
 ```bash
+#!/bin/bash
+
 hangar load \
-    --file=example_image_list.txt \
-    --source=save_example.zip \
+    --file="example_image_list.txt" \
+    --source="save_example.zip" \
     --destination=DESTINATION_REGISTRY_URL \
     --arch=amd64,arm64 \
     --os=linux \
     --jobs=4
 ```
 
+## Harbor 2.X
+
+Hangar will try to create **Harbor Project** automatically on `load` command if the destination registry is harbor.
+
+You need to create **Harbor Project** manually if Hangar can't create the project automatically, or the image will fail to copy.
+
 ## Usage
 
 ```txt title="hanagr load --help"
@@ -64,12 +72,6 @@ Global Flags:
 Use "hangar load [command] --help" for more information about a command.
 ```
 
-## Harbor 2.X
-
-Hangar will try to create **Harbor Project** automatically on `load` command if the destination registry is harbor.
-
-You need to create **Harbor Project** manually if Hangar can't create the project automatically, or the image will fail to copy.
-
 ## Load from different architecture archives
 
 This feature allows you to sequentially load container images from multiple archive files containing different architectures.
@@ -111,7 +113,7 @@ Here is an example:
         {
           "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
           "size": 1235,
-          "digest":     "sha256:7dcde3f4d7eec9ccd22f2f6873a1f0b10be189405dcbfbaac417487e4fb44c4b",
+          "digest": "sha256:7dcde3f4d7eec9ccd22f2f6873a1f0b10be189405dcbfbaac417487e4fb44c4b",
           "platform": {
             "architecture": "amd64",
             "os": "linux"
@@ -138,7 +140,7 @@ Here is an example:
         {
           "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
           "size": 1230,
-          "digest":     "sha256:66f1a9ae96f5a18068fcbd53e0171c78b40adffa3d70f565341eb453a34bb099",
+          "digest": "sha256:66f1a9ae96f5a18068fcbd53e0171c78b40adffa3d70f565341eb453a34bb099",
           "platform": {
             "architecture": "arm64",
             "os": "linux",
@@ -148,7 +150,7 @@ Here is an example:
         {
           "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
           "size": 1235,
-          "digest":     "sha256:7dcde3f4d7eec9ccd22f2f6873a1f0b10be189405dcbfbaac417487e4fb44c4b",
+          "digest": "sha256:7dcde3f4d7eec9ccd22f2f6873a1f0b10be189405dcbfbaac417487e4fb44c4b",
           "platform": {
             "architecture": "amd64",
             "os": "linux"

docs/12-load/02-validate.md

@@ -9,9 +9,11 @@ The `hangar load validate` command (subcommand of `hangar load`) is used for ens
 Verify the loaded images according to image list file after executing the [load](load#quick-start) command:
 
 ```bash
+#!/bin/bash
+
 hangar load validate \
-    --file=example_image_list.txt \
-    --source=save_example.zip \
+    --file="example_image_list.txt" \
+    --source="save_example.zip" \
     --destination=DESTINATION_REGISTRY_URL \
     --arch=amd64,arm64 \
     --os=linux \

docs/13-sync/01-sync.md

@@ -11,6 +11,8 @@ If some images fail to download when running the [save](../save/save) command, y
 Use following command to append new container images to the existing archive file created by [save](../save/save#quick-start) command parallelly:
 
 ```bash
+#!/bin/bash
+
 hangar sync \
     --file="extra_image_list.txt" \
     --source="docker.io" \

docs/13-sync/02-validate.md

@@ -9,6 +9,8 @@ The `hangar sync validate` command (subcommand of `hangar save`) is similar to `
 Verify the synced (appended) images according to image list file after executing the [sync](sync#quick-start) command:
 
 ```bash
+#!/bin/bash
+
 hangar sync validate \
     --file="extra_image_list.txt" \
     --source="docker.io" \

docs/14-advanced-usage/02-archive-ls.md

@@ -9,6 +9,8 @@ The `hangar archive ls` command supports listing the images in the archive file.
 Use following command to list images in archive file created by [save](../save/save) command:
 
 ```bash
+#!/bin/bash
+
 hangar archive ls --file="save_example.zip"
 ```
 

docs/14-advanced-usage/04-convert-list.md

@@ -2,7 +2,13 @@
 title: "Convert image list format"
 ---
 
-The `convert-list` command allows to convert image list format from `default` format to the `mirror` format (see [image list format specification](../mirror/image-list-format)).
+The `hangar convert-list` command allows to convert image list format from `default` format to the `mirror` format (see [image list format specification](../mirror/image-list-format)).
+
+:::note
+
+The `mirror` command supports both `default` and `mirror` format image list files. You can use the `mirror` command to copy container images with the `default` format image list file directly.
+
+:::
 
 ## Quick Start
 

docs/14-advanced-usage/05-completion.md

@@ -0,0 +1,46 @@
+---
+title: "Shell Completion"
+---
+
+The `hangar completion` command allows to generate a shell completion script for different shells.
+
+## Quick Start
+
+Execute following command to enable Hangar shell completion.
+
+- For `bash`:
+
+    ```bash
+    echo 'source <(hangar completion bash)' >> ~/.bashrc && source ~/.bashrc
+    ```
+
+- For `zsh`:
+
+    ```bash
+    echo 'source <(hangar completion zsh)' >> ~/.zshrc && source ~/.zshrc
+    ```
+
+## Usage
+
+```txt title="hangar completion --help"
+Generate the autocompletion script for hangar for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+Usage:
+  hangar completion [command]
+
+Available Commands:
+  bash        Generate the autocompletion script for bash
+  fish        Generate the autocompletion script for fish
+  powershell  Generate the autocompletion script for powershell
+  zsh         Generate the autocompletion script for zsh
+
+Flags:
+  -h, --help   help for completion
+
+Global Flags:
+      --debug             enable debug output
+      --insecure-policy   run Hangar without policy check
+
+Use "hangar completion [command] --help" for more information about a command.
+```

docs/14-advanced-usage/05-generate-list.md → docs/14-advanced-usage/99-generate-list.md

@@ -4,12 +4,18 @@ title: "Generate Rancher image list"
 
 The `hangar generate-list` command allows to generate a image list according to Rancher Version.
 
-## QuickStart
+:::warning
+
+The `hangar generate-list` command is only used for testing purpose. Please download the official `rancher-images.txt` image list file on Rancher GitHub [Release page](https://github.com/rancher/rancher/releases).
+
+:::
+
+## Quick Start
 
 According to the Rancher version, get the latest KDM data, and clone chart repos to local to generate a image-list used by Rancher:
 
 ```sh
-hangar generate-list -rancher="v2.7.0"
+hangar generate-list --rancher="v2.7.0"
 ```
 
 The image-list generated by this tool only includes images in the KDM data and Chart repositories that matching the Rancher version.

docs/15-dev/01-build.md

@@ -15,7 +15,7 @@ You can follow the below instructions to build hangar executable binary.
     ```bash
     git clone https://github.com/hangar.git && cd hangar
     ```
-1. Build hangar by using `make`:
+1. Build hangar in container by executing `make` commands:
     ```bash
     # Get help information
     make help

docs/99-questions.md

@@ -36,11 +36,11 @@ See [archive](save/archive) page.
 
     See [hangar archive](save/archive) for more information of the new archive format.
 
-2. Error: `manifest unknown`
+1. Error: `manifest unknown`
 
     The image to be copy does not exists. you can use `hangar inspect --raw docker://<IMAGE>` to check whether the image exists or not.
 
-3. Error: `unsupported MIME type`
+1. Error: `unsupported MIME type`
 
     The `mediaType` of the image manifest is not supported.
 
@@ -52,7 +52,13 @@ See [archive](save/archive) page.
     - `application/vnd.oci.image.manifest.v1+json`
     - `application/vnd.oci.image.index.v1+json`
 
-4. Warning: `no avaiable image for specified arch and os`
+1. Error: `open /etc/containers/policy.json: no such file or directory`
+
+    The policy config file `/etc/containers/policy.json` does not exists, you can obtain a default policy file at [default-policy.json](https://github.com/cnrancher/hangar/blob/main/default-policy.json).
+
+    Or you can execute hangar with `--insecure-policy` option.
+
+1. Warning: `no avaiable image for specified arch and os`
 
     The architecture / OS of the image to be copied does not match the architecture & OS specified by the `--arch` and `--os` parameter.
 

docusaurus.config.js

@@ -78,10 +78,6 @@ const config = {
                         },
                     ],
                 },
-                {
-                    type: "search",
-                    position: "right",
-                },
                 {
                     type: "localeDropdown",
                     position: "right",
@@ -96,6 +92,10 @@ const config = {
                         },
                     ],
                 },
+                {
+                    type: "search",
+                    position: "right",
+                },
             ],
         },
         footer: {