Broken redirects in README and `en` directory

[TracerDS]

README.md redirects as well as any other redirect in the en directory for the repo are broken.
They point to nonexisting/moved files (docs)
Some examples include but are not limited to:

• README
• AI Assisted Vulkan
• Building_a_Simple_Engine
• GUI

[SaschaWillems]

Can you elaborate? The site is not meant to be viewed through github but uses Antora as a site generator instead, so links might seem broken in the repo while in reality they arent'.

[TracerDS]

Can you elaborate? The site is not meant to be viewed through github but uses Antora as a site generator instead, so links might seem broken in the repo while in reality they arent'.

The links redirect to nonexisting pages. e.g. In AI Assisted Vulkan Chapter 3.5 redirects to /blob/main/en/AI_Assisted_Vulkan/AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc while the actual file path is /blob/main/en/AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc

- /blob/main/en/AI_Assisted_Vulkan/AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc
+ /blob/main/en/AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc

Same with Building a Simple Engine:

- /blob/main/en/Building_a_Simple_Engine/00_Introduction.adoc
+ /blob/main/en/00_Introduction.adoc

- means the current version. + means the actual/working version

[SaschaWillems]

I just checked with an Antora build of the docs site and cannot confirm. As noted above, you're not supposed to work through the pages via this github repo but rather via an Antore site build e,g, at https://docs.vulkan.org/.

There e.g. the link to the lora chapter works fine: https://docs.vulkan.org/tutorial/latest/AI_Assisted_Vulkan/03_model_selection_specialization/04_rag_mcp_specialization.html

[TracerDS]

I just checked with an Antora build of the docs site and cannot confirm. As noted above, you're not supposed to work through the pages via this github repo but rather via an Antore site build e,g, at https://docs.vulkan.org/.

There e.g. the link to the lora chapter works fine: https://docs.vulkan.org/tutorial/latest/AI_Assisted_Vulkan/03_model_selection_specialization/04_rag_mcp_specialization.html

On Antora it works fine because the cwd (current working directory) path changes.
Lets take a look at AIAV:
Chapter 3.5 redirection is defined as:

<a href="03_model_selection_specialization/05_fine_tuning_lora.html" class="xref page">Chapter 3.5</a>

When you go to the adoc file, it is defined as:

[...] see xref:AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc[Chapter 3.5].

Since the cwd changes while traversing through the directories, going into AI_Assisted_Vulkan/03_model_selection_specialization/05_fine_tuning_lora.adoc while being in the 09_faq.adoc file will cause the cwd to be AI_Assisted_Vulkan instead of en as Antora assumes.

After your comments I am now aware that you should use the website. However seeing as adoc files are perfectly legal alternative for markdown files it can cause a lot of confusion when just looking at the README file.

[SaschaWillems]

Thanks. We'll add a hint to the readme to avoid further onfusion.

[TracerDS]

Wouldnt it be better to change the cwd of antora accordingly?
That way both would work

[SaschaWillems]

That would be a change to the build process. The site was designed to be viewed through docs.vulkan.org as I noted above. Esp. with github's asciidoc support being too limited and also not supporting Antora added functionality.

[iagoCL]

I mentioned this in #497.

I believe we should update the links in README.adoc and make a few other small changes.

As far as I can tell, the main README.adoc is not included in the Antora-generated documentation, or at least I cannot find it here.

In my view, the main README.adoc should be treated as an exception and optimized for GitHub, so we should change its links. Its purpose should be to guide people who land on the GitHub repository.

I think many of our users find us through GitHub, and the README is the first thing they see. Currently, it does not do a good job of explaining what this repository is or helping visitors find the information they need.