Docs: fix broken internal links and ensure they stay fixed (cvat-ai#7695

)

We have quite a few broken links, which is unsurprising, as Hugo does
not help detect them.

This patch adds a custom shortcode (`ilink`) which validates the target
path and then renders as a link. It rewrites most internal links to use
this shortcode, and fixes those which were broken.

Originally, I was just going to use the builtin `relref` shortcode to
build the URLs, but it turns out that that does not play well with
remark. It becomes confused and thinks you forgot to specify the URL
altogether. `ilink` replaces the entire link, so remark has nothing to
complain about. `ilink` supports a default link text, although I haven't
yet used this anywhere.

I also "fortified" the "about" link in `navbar.html`, although templates
don't support shortcodes, so I just used the `relref` function.

A few links I had to keep as-is for various reasons:

* Links from the `docs/_index.md`, because they are inside a shortcode,
  and as far as I can tell, you can't put shortcodes in shortcode
  parameters.

* The refresh URLs in `home.html` and `404.html`, for complicated
  reasons.

* Links to autogenerated API documentation pages due to some known
  problems with generating those pages for previous releases.

Finally, I had to update `build_docs.py`, because it neglected to check
out `page_404.html` when rendering the docs for previous versions, and
the new version of `page_404.html` will not render without the new
shortcode.

site/build_docs.py

@@ -60,8 +60,7 @@ def git_checkout(ref: str, temp_repo: git.Repo, temp_dir: Path):
     # We need to checkout with submodules, recursively
 
     subdirs = [
-        "site/content/en/docs",
-        "site/content/en/images",
+        "site/content",
         "site/assets",
         "site/layouts/partials",
         "site/layouts/shortcodes",

site/content/en/docs/administration/advanced/analytics.md

@@ -49,7 +49,8 @@ The CVAT analytics is based on Vector, ClickHouse, and Grafana.
 CVAT and its analytics module can be set up locally, for
 self-hosted solution analytics are enabled by default.
 
-> For detailed instructions for CVAT installation, see [Installation Guide](https://opencv.github.io/cvat/docs/administration/basics/installation/)
+> For detailed CVAT installation instructions, see
+> {{< ilink "/docs/administration/basics/installation" "Installation Guide" >}}
 > or refer to the [CVAT Course](https://www.youtube.com/playlist?list=PL0to7Ng4PuuYQT4eXlHb_oIlq_RPeuasN)
 > for installation videos.
 
@@ -64,7 +65,7 @@ docker compose up -d
 
 If you cannot access analytics on
 development environnement,
-see [Analytics Ports](/docs/contributing/development-environment/#cvat-analytics-ports)
+see {{< ilink "/docs/contributing/development-environment#cvat-analytics-ports" "Analytics Ports" >}}
 
 ### Events log structure
 

site/content/en/docs/administration/advanced/backup_guide.md

@@ -23,7 +23,8 @@ Docker volumes are used to store all CVAT data:
 - `cvat_logs`: used to store logs of CVAT backend processes managed by supevisord.
   Mounted into `cvat` container by `/home/django/logs` path.
 
-- `cvat_events`: this is an optional volume that is used only when [Analytics component](/docs/administration/advanced/analytics/)
+- `cvat_events`: this is an optional volume that is used only when
+  {{< ilink "/docs/administration/advanced/analytics" "Analytics component" >}}
   is enabled and is used to store Elasticsearch database files.
   Mounted into `cvat_elasticsearch` container by `/usr/share/elasticsearch/data` path.
 
@@ -62,7 +63,8 @@ it will not work because between CVAT releases the layout of DB can be
 changed. You always can upgrade CVAT later. It will take care to migrate
 your data properly internally.**
 
-Note: CVAT containers must exist (if no, please follow the [installation guide](/docs/administration/basics/installation/#quick-installation-guide)).
+Note: CVAT containers must exist (if no, please follow the
+{{< ilink "/docs/administration/basics/installation#quick-installation-guide" "installation guide" >}}).
 Stop all CVAT containers:
 
 ```shell

site/content/en/docs/administration/advanced/installation_automatic_annotation.md

@@ -77,7 +77,7 @@ description: 'Information about the installation of components needed for semi-a
   - The number of GPU deployed functions will be limited to your GPU memory.
   - See [deploy_gpu.sh](https://github.com/cvat-ai/cvat/blob/develop/serverless/deploy_gpu.sh)
     script for more examples.
-  - For some models (namely [SiamMask](/docs/manual/advanced/ai-tools#trackers)) you need an [Nvidia driver](https://www.nvidia.com/en-us/drivers/unix/)
+  - For some models (namely {{< ilink "/docs/manual/advanced/ai-tools#trackers" "SiamMask" >}}) you need an [Nvidia driver](https://www.nvidia.com/en-us/drivers/unix/)
     version greater than or equal to 450.80.02.
 
   **Note for Windows users:**

site/content/en/docs/administration/advanced/upgrade_guide.md

@@ -15,13 +15,14 @@ upgrading PostgreSQL base image major version. See details [here](#how-to-upgrad
 To upgrade CVAT, follow these steps:
 
 - It is highly recommended backup all CVAT data before updating, follow the
-  [backup guide](/docs/administration/advanced/backup_guide/) and backup all CVAT volumes.
+  {{< ilink "/docs/administration/advanced/backup_guide" "backup guide" >}} and backup all CVAT volumes.
 
 - Go to the previously cloned CVAT directory and stop all CVAT containers with:
   ```shell
   docker compose down
   ```
-  If you have included [additional components](/docs/administration/basics/installation/#additional-components),
+  If you have included
+  {{< ilink "/docs/administration/basics/installation#additional-components" "additional components" >}},
   include all compose configuration files that are used, e.g.:
   ```shell
   docker compose -f docker-compose.yml -f components/serverless/docker-compose.serverless.yml down
@@ -30,16 +31,17 @@ To upgrade CVAT, follow these steps:
 - Update CVAT source code by any preferable way: clone with git or download zip file from GitHub.
   Note that you need to download the entire source code, not just the Docker Compose configuration file.
   Check the
-  [installation guide](/docs/administration/basics/installation/#how-to-get-cvat-source-code) for details.
+  {{< ilink "/docs/administration/basics/installation#how-to-get-cvat-source-code" "installation guide" >}} for details.
 
 - Verify settings:
   The installation process is changed/modified from version to version and
   you may need to export some environment variables, for example
-  [CVAT_HOST](/docs/administration/basics/installation/#use-your-own-domain).
+  {{< ilink "/docs/administration/basics/installation#use-your-own-domain" "CVAT_HOST" >}}.
 
 - Update local CVAT images.
   Pull or build new CVAT images, see
-  [How to pull/build/update CVAT images section](/docs/administration/basics/installation/#how-to-pullbuildupdate-cvat-images)
+  {{< ilink "/docs/administration/basics/installation#how-to-pullbuildupdate-cvat-images"
+    "How to pull/build/update CVAT images section" >}}
   for details.
 
 - Start CVAT with:
@@ -101,7 +103,7 @@ docker compose up -d
 ## How to upgrade PostgreSQL database base image
 
 1. It is highly recommended backup all CVAT data before updating, follow the
-   [backup guide](/docs/administration/advanced/backup_guide/) and backup CVAT database volume.
+   {{< ilink "/docs/administration/advanced/backup_guide" "backup guide" >}} and backup CVAT database volume.
 
 1. Run previously used CVAT version as usual
 
@@ -122,7 +124,8 @@ docker compose up -d
 
 1. Update CVAT source code by any preferable way: clone with git or download zip file from GitHub.
    Check the
-   [installation guide](/docs/administration/basics/installation/#how-to-get-cvat-source-code) for details.
+   {{< ilink "/docs/administration/basics/installation#how-to-get-cvat-source-code" "installation guide" >}}
+   for details.
 
 1. Start database container only:
    ```shell

site/content/en/docs/administration/advanced/webhooks.md

@@ -47,7 +47,7 @@ See:
 
 To create a webhook for **Project**, do the following:
 
-1. [Create a Project](/docs/manual/advanced/projects/).
+1. {{< ilink "/docs/manual/advanced/projects" "Create a Project" >}}.
 2. Go to the **Projects** and click on the project's widget.
 3. In the top right corner, click **Actions** > **Setup Webhooks**.
 4. In the top right corner click **+**
@@ -60,7 +60,7 @@ To create a webhook for **Project**, do the following:
 
 To create a webhook for **Organization**, do the following:
 
-1. [Create Organization](/docs/manual/advanced/organization/)
+1. {{< ilink "/docs/manual/advanced/organization" "Create Organization" >}}
 2. Go to the **Organization** > **Settings** > **Actions** > **Setup Webhooks**.
 3. In the top right corner click **+**
 

site/content/en/docs/administration/basics/AWS-Deployment-Guide.md

@@ -19,7 +19,7 @@ There are two ways of deploying the CVAT.
    link.
 
 2. **On Any other AWS Machine:** We can follow the same instruction guide mentioned in the
-   [installation instructions](/docs/administration/basics/installation/).
+   {{< ilink "/docs/administration/basics/installation" "installation instructions" >}}.
    The additional step is to add a [security group and rule to allow incoming connections](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html).
 
 For any of above, don't forget to set the `CVAT_HOST` environment variable to the exposed

site/content/en/docs/administration/basics/admin-account.md

@@ -16,7 +16,7 @@ to assign groups (roles) to other users.
 ### Prerequisites
 
 Before you register an admin account (superuser), you need to install CVAT locally,
-see [Installation Guide](/docs/administration/basics/installation/).
+see {{< ilink "/docs/administration/basics/installation" "Installation Guide" >}}.
 
 Steps of installation are partly different, depending on the type of operation system (OS).
 

site/content/en/docs/administration/basics/installation.md

@@ -126,7 +126,7 @@ For access from China, read [sources for users from China](#sources-for-users-fr
 - Open the installed Google Chrome browser and go to [localhost:8080](http://localhost:8080).
   Type your login/password for the superuser on the login page and press the _Login_
   button. Now you should be able to create a new annotation task. Please read the
-  [CVAT manual](/docs/manual/) for more details.
+  {{< ilink "/docs/manual" "CVAT manual" >}} for more details.
 
 ## Windows 10
 
@@ -209,7 +209,7 @@ For access from China, read [sources for users from China](#sources-for-users-fr
 - Open the installed Google Chrome browser and go to [localhost:8080](http://localhost:8080).
   Type your login/password for the superuser on the login page and press the _Login_
   button. Now you should be able to create a new annotation task. Please read the
-  [CVAT manual](/docs/manual/) for more details.
+  {{< ilink "/docs/manual" "CVAT manual" >}} for more details.
 
 ## Mac OS Mojave
 
@@ -285,7 +285,7 @@ For access from China, read [sources for users from China](#sources-for-users-fr
 - Open the installed Google Chrome browser and go to [localhost:8080](http://localhost:8080).
   Type your login/password for the superuser on the login page and press the _Login_
   button. Now you should be able to create a new annotation task. Please read the
-  [CVAT manual](/docs/manual/) for more details.
+  {{< ilink "/docs/manual" "CVAT manual" >}} for more details.
 
 ## Advanced Topics
 
@@ -438,7 +438,7 @@ if you want to keep the dashboard in production you should read Traefik's
 
 #### Semi-automatic and automatic annotation
 
-Please follow this [guide](/docs/administration/advanced/installation_automatic_annotation/).
+Please follow this {{< ilink "/docs/administration/advanced/installation_automatic_annotation" "guide" >}}.
 
 ### Stop all containers
 
@@ -488,7 +488,7 @@ volumes:
 
 You can change the share device path to your actual share.
 
-You can [mount](/docs/administration/advanced/mounting_cloud_storages/)
+You can {{< ilink "/docs/administration/advanced/mounting_cloud_storages" "mount" >}}
 your cloud storage as a FUSE and use it later as a share.
 
 ### Email verification

site/content/en/docs/api_sdk/cli/_index.md

@@ -83,10 +83,10 @@ optional arguments:
 ### Create
 
 Description of the options you can find in
-[Creating an annotation task](/docs/manual/basics/creating_an_annotation_task/) section.
+{{< ilink "/docs/manual/basics/create_an_annotation_task" "Creating an annotation task" >}} section.
 
 For create a task you need file contain labels in the `json` format, you can create a JSON label specification
-by using the [label constructor](/docs/manual/basics/creating_an_annotation_task/#labels).
+by using the {{< ilink "/docs/manual/basics/create_an_annotation_task#labels" "label constructor" >}}.
 <details>
 <summary>Example JSON labels file</summary>
 
@@ -227,7 +227,7 @@ by using the [label constructor](/docs/manual/basics/creating_an_annotation_task
 ### Auto-annotate
 
 This command provides a command-line interface
-to the [auto-annotation API](/docs/api_sdk/sdk/auto-annotation).
+to the {{< ilink "/docs/api_sdk/sdk/auto-annotation" "auto-annotation API" >}}.
 
 It can auto-annotate using AA functions implemented in one of the following ways:
 

site/content/en/docs/api_sdk/sdk/_index.md

@@ -12,10 +12,14 @@ simplify server interaction and provide additional functionality like data valid
 and serialization.
 
 SDK API includes several layers:
-- Low-level API with REST API wrappers. Located at `cvat_sdk.api_client`. [Read more](/docs/api_sdk/sdk/lowlevel-api)
-- High-level API. Located at `cvat_sdk.core`. [Read more](/docs/api_sdk/sdk/highlevel-api)
-- PyTorch adapter. Located at `cvat_sdk.pytorch`. [Read more](/docs/api_sdk/sdk/pytorch-adapter)
-- Auto-annotation API. Located at `cvat_sdk.auto_annotation.` [Read more](/docs/api_sdk/sdk/auto-annotation)
+- Low-level API with REST API wrappers. Located at `cvat_sdk.api_client`.
+  {{< ilink "/docs/api_sdk/sdk/lowlevel-api" "Read more" >}}
+- High-level API. Located at `cvat_sdk.core`.
+  {{< ilink "/docs/api_sdk/sdk/highlevel-api" "Read more" >}}
+- PyTorch adapter. Located at `cvat_sdk.pytorch`.
+  {{< ilink "/docs/api_sdk/sdk/pytorch-adapter" "Read more" >}}
+- Auto-annotation API. Located at `cvat_sdk.auto_annotation.`
+  {{< ilink "/docs/api_sdk/sdk/auto-annotation" "Read more" >}}
 
 In general, the low-level API provides single-request operations, while the high-level one
 implements composite, multi-request operations, and provides local proxies for server objects.

site/content/en/docs/api_sdk/sdk/auto-annotation.md

@@ -35,7 +35,7 @@ The layer can be divided into several parts:
 
 The `auto-annotate` CLI command provides a way to use an AA function from the command line
 rather than from a Python program.
-See [the CLI documentation](/docs/api_sdk/cli/) for details.
+See {{< ilink "/docs/api_sdk/cli" "the CLI documentation" >}} for details.
 
 ## Example
 

site/content/en/docs/contributing/development-environment.md

@@ -219,7 +219,7 @@ description: 'Installing a development environment for different operating syste
 
 
 You have done! Now it is possible to insert breakpoints and debug server and client of the tool.
-Instructions for running tests locally are available [here](/docs/contributing/running-tests/).
+Instructions for running tests locally are available {{< ilink "/docs/contributing/running-tests" "here" >}}.
 
 ## Note for Windows users
 

site/content/en/docs/contributing/new-annotation-format.md

@@ -142,17 +142,17 @@ task_data.add_shape(shape)
 
 ## Format specifications
 
-- [CVAT](/docs/manual/advanced/formats/format-cvat/)
-- [Datumaro](/docs/manual/advanced/formats/format-datumaro/)
-- [LabelMe](/docs/manual/advanced/formats/format-labelme/)
-- [MOT](/docs/manual/advanced/formats/format-mot/)
-- [MOTS](/docs/manual/advanced/formats/format-mots/)
-- [COCO](/docs/manual/advanced/formats/format-coco/)
-- [PASCAL VOC and mask](/docs/manual/advanced/formats/format-voc/)
-- [YOLO](/docs/manual/advanced/formats/format-yolo/)
-- [ImageNet](/docs/manual/advanced/formats/format-imagenet/)
-- [CamVid](/docs/manual/advanced/formats/format-camvid/)
-- [WIDER Face](/docs/manual/advanced/formats/format-widerface/)
-- [VGGFace2](/docs/manual/advanced/formats/format-vggface2/)
-- [Market-1501](/docs/manual/advanced/formats/format-market1501/)
-- [ICDAR13/15](/docs/manual/advanced/formats/format-icdar/)
+- {{< ilink "/docs/manual/advanced/formats/format-cvat" "CVAT" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-datumaro" "Datumaro" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-labelme" "LabelMe" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-mot" "MOT" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-mots" "MOTS" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-coco" "COCO" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-voc" "PASCAL VOC and mask" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-yolo" "YOLO" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-imagenet" "ImageNet" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-camvid" "CamVid" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-widerface" "WIDER Face" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-vggface2" "VGGFace2" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-market1501" "Market-1501" >}}
+- {{< ilink "/docs/manual/advanced/formats/format-icdar" "ICDAR13/15" >}}

site/content/en/docs/contributing/running-tests.md

@@ -46,7 +46,7 @@ yarn run cypress:run:chrome:canvas3d
 
 **Initial steps**
 
-1. Follow [this guide](/docs/api_sdk/sdk/developer-guide/) to prepare
+1. Follow {{< ilink "/docs/api_sdk/sdk/developer-guide" "this guide" >}} to prepare
    `cvat-sdk` and `cvat-cli` source code
 1. Install all necessary requirements before running REST API tests:
    ```

site/content/en/docs/contributing/setup-additional-components.md

@@ -7,7 +7,7 @@ description: 'Deploying a DL model as a serverless function and Cypress tests.'
 
 ## DL models as serverless functions
 
-Follow this [guide](/docs/administration/advanced/installation_automatic_annotation/) to install Nuclio:
+Follow this {{< ilink "/docs/administration/advanced/installation_automatic_annotation" "guide" >}} to install Nuclio:
 
 - You have to install `nuctl` command line tool to build and deploy serverless
   functions.

site/content/en/docs/enterprise/shapes-converter.md

@@ -64,7 +64,7 @@ To convert shapes, do the following:
 
    ![](/images/shapes-converter-annotated-dataset.jpg)
 
-2. Set up [filters](/docs/manual/advanced/filter/).
+2. Set up {{< ilink "/docs/manual/advanced/filter" "filters" >}}.
 
    ![](/images/shapes-converter-setup-filter.png)
 

site/content/en/docs/faq.md

@@ -9,12 +9,12 @@ description: 'Answers to frequently asked questions'
 
 ## How to migrate data from CVAT.org to CVAT.ai
 
-Please follow the [export tasks and projects guide](/docs/manual/advanced/backup/#backup) to
+Please follow the {{< ilink "/docs/manual/advanced/backup#backup" "export tasks and projects guide" >}} to
 download an archive with data which corresponds to your task or project. The backup for a
 project will have all tasks which are inside the project. Thus you don't need to export
 them separately.
 
-Please follow the [import tasks and projects guide](/docs/manual/advanced/backup/#create-from-backup)
+Please follow the {{< ilink "/docs/manual/advanced/backup#create-from-backup" "import tasks and projects guide" >}}
 to upload your backup with a task or project to a CVAT instance.
 
 See a quick demo below. It is really a simple process. If your data is huge, it may take some time.
@@ -26,10 +26,10 @@ Please be patient.
 
 ## How to upgrade CVAT
 
-Before upgrading, please follow the [backup guide](/docs/administration/advanced/backup_guide/)
+Before upgrading, please follow the {{< ilink "/docs/administration/advanced/backup_guide" "backup guide" >}}
 and backup all CVAT volumes.
 
-Follow the [upgrade guide](/docs/administration/advanced/upgrade_guide/).
+Follow the {{< ilink "/docs/administration/advanced/upgrade_guide" "upgrade guide" >}}.
 
 ## How to change default CVAT hostname or port
 
@@ -113,14 +113,14 @@ volumes:
 
 ## How to mark job/task as completed
 
-The status is set by the user in the [Info window](/docs/manual/basics/top-panel/#info)
+The status is set by the user in the {{< ilink "/docs/manual/basics/top-panel#info" "Info window" >}}
 of the job annotation view.
 There are three types of status: annotation, validation or completed.
 The status of the job changes the progress bar of the task.
 
 ## How to install CVAT on Windows 10 Home
 
-Follow this [guide](/docs/administration/basics/installation/#windows-10).
+Follow this {{< ilink "/docs/administration/basics/installation#windows-10" "guide" >}}.
 
 ## I do not have the Analytics tab on the header section. How can I add analytics
 
@@ -151,16 +151,18 @@ To do this, you will need to edit `traefik.http.<router>.cvat.rule` docker label
 ## How to create a task with multiple jobs
 
 Set the segment size when you create a new task, this option is available in the
-[Advanced configuration](/docs/manual/basics/creating_an_annotation_task/#advanced-configuration)
+{{< ilink "/docs/manual/basics/create_an_annotation_task#advanced-configuration" "Advanced configuration" >}}
 section.
 
 ## How to transfer CVAT to another machine
 
-Follow the [backup/restore guide](/docs/administration/advanced/backup_guide/#how-to-backup-all-cvat-data).
+Follow the
+{{< ilink "/docs/administration/advanced/backup_guide#how-to-backup-all-cvat-data" "backup/restore guide" >}}.
 
 ## How to load your own DL model into CVAT
 
-See the information here in the [Serverless tutorial](/docs/manual/advanced/serverless-tutorial/#adding-your-own-dl-models).
+See the information here in the
+{{< ilink "/docs/manual/advanced/serverless-tutorial#adding-your-own-dl-models" "Serverless tutorial" >}}.
 
 ## My server uses a custom SSL certificate and I don't want to check it.