Fix broken links in Slang docs (#7039)

This change fixes some broken links/anchors in the Slang docs that I found after running a link checker tool on the readthedocs site.
Some of these were broken on GitHub Pages as well, such as anchors with apostrophes or docs that were moved.

The doc writer change adds an explicit .html extension to Parameter links, so that Sphinx/RTD does not treat it as an anchor.

8 files changed, 16 insertions, 15 deletions

diff --git a/docs/user-guide/02-conventional-features.md b/docs/user-guide/02-conventional-features.md
index 695d61e81..21387af3e 100644
--- a/docs/user-guide/02-conventional-features.md
+++ b/docs/user-guide/02-conventional-features.md
@@ -1065,7 +1065,7 @@ struct GenerateCtor1 : GenerateCtorInner1
 GenerateCtor1 val[2] = { { 3 }, { 2 } };
 ```
 
-In addition, Slang also provides compatibility support for C-style initializer lists with `struct`s. C-style initializer lists can use [Partial Initializer List's](#Partial-Initializer-List's) and [Flattened Array Initializer With Struct's](#Flattened-Array-Initializer-With-Struct)
+In addition, Slang also provides compatibility support for C-style initializer lists with `struct`s. C-style initializer lists can use [Partial Initializer List's](#Partial-Initializer-Lists) and [Flattened Array Initializer With Struct's](#Flattened-Array-Initializer-With-Structs)
 
 A struct is considered a C-style struct if:
 1. User never defines a custom constructor with **more than** 0 parameters
diff --git a/docs/user-guide/06-interfaces-generics.md b/docs/user-guide/06-interfaces-generics.md
index bc2ab88df..b90bc04ba 100644
--- a/docs/user-guide/06-interfaces-generics.md
+++ b/docs/user-guide/06-interfaces-generics.md
@@ -806,7 +806,7 @@ void main()
 }
 
 ```
-See  [if-let syntax](convenience-features.html#if_let-syntax) for more details.
+See  [if-let syntax](03-convenience-features.html#if_let-syntax) for more details.
 
 
 Generic Interfaces
diff --git a/docs/user-guide/08-compiling.md b/docs/user-guide/08-compiling.md
index 29a1591d5..3f895a8c3 100644
--- a/docs/user-guide/08-compiling.md
+++ b/docs/user-guide/08-compiling.md
@@ -861,7 +861,7 @@ program->link(linkedProgram.writeRef(), diagnosticBlob.writeRef());
 ```
 
 The linking step is also used to perform link-time specialization, which is a recommended approach for shader specialization
-compared to preprocessor based specialization. Please see [Link-time Specialization and Precompiled Modules](link-time-specialization) for more details.
+compared to preprocessor based specialization. Please see [Link-time Specialization and Precompiled Modules](10-link-time-specialization) for more details.
 
 Any diagnostic messages related to linking (for example, if an external symbol cannot be resolved) will be written to `diagnosticBlob`.
 
@@ -903,7 +903,7 @@ This assumes Slang has been built with the C++ multithreaded runtime, as is the
 
 All other functions and methods are not [reentrant](https://en.wikipedia.org/wiki/Reentrancy_(computing)) and can only execute on a single thread. More precisely, functions and methods can only be called on a *single* thread at *any one time*. This means for example a global session can be used across multiple threads, as long as some synchronization enforces that only one thread can be in a Slang call at any one time.
 
-Much of the Slang API is available through [COM interfaces](https://en.wikipedia.org/wiki/Component_Object_Model). In strict COM, interfaces should be atomically reference counted. Currently *MOST* Slang API COM interfaces are *NOT* atomic reference counted. One exception is the `ISlangSharedLibrary` interface when produced from [host-callable](cpu-target.md#host-callable). It is atomically reference counted, allowing it to persist and be used beyond the original compilation and be freed on a different thread. 
+Much of the Slang API is available through [COM interfaces](https://en.wikipedia.org/wiki/Component_Object_Model). In strict COM, interfaces should be atomically reference counted. Currently *MOST* Slang API COM interfaces are *NOT* atomic reference counted. One exception is the `ISlangSharedLibrary` interface when produced from [host-callable](../cpu-target.md#host-callable). It is atomically reference counted, allowing it to persist and be used beyond the original compilation and be freed on a different thread. 
 
 
 ## Compiler Options
diff --git a/docs/user-guide/09-reflection.md b/docs/user-guide/09-reflection.md
index bf09d04e0..ad2047a82 100644
--- a/docs/user-guide/09-reflection.md
+++ b/docs/user-guide/09-reflection.md
@@ -21,14 +21,14 @@ Compiling a Program
 -------------------
 
 The first step in reflecting a shader program is, unsurprisingly, to compile it.
-Currently reflection information cannot be queried from code compiled via the command-line `slangc` tool, so applications that want to perform reflection on Slang shader code should use the [compilation API](./compiling#using-the-compilation-api) to compile a program, and then use `getLayout()` to extract reflection information:
+Currently reflection information cannot be queried from code compiled via the command-line `slangc` tool, so applications that want to perform reflection on Slang shader code should use the [compilation API](08-compiling#using-the-compilation-api) to compile a program, and then use `getLayout()` to extract reflection information:
 
 ```c++
 slang::IComponentType* program = ...;
 slang::ProgramLayout* programLayout = program->getLayout(targetIndex);
 ```
 
-For more information, see the [relevant section](./compiling#layout-and-reflection) of the chapter on compilation.
+For more information, see the [relevant section](08-compiling#layout-and-reflection) of the chapter on compilation.
 
 Types and Variables
 -------------------
diff --git a/docs/user-guide/a1-special-topics.md b/docs/user-guide/a1-special-topics.md
index f0412b6be..0e4edd23a 100644
--- a/docs/user-guide/a1-special-topics.md
+++ b/docs/user-guide/a1-special-topics.md
@@ -9,7 +9,7 @@ This chapter covers several additional topics on using Slang. These topics do no
 
 In this chapter:
 1. [Handling matrix layout differences on different platforms](a1-01-matrix-layout.md)
-2. [Using Slang to write PyTorch kernels](a1-02-slangpy.md)
+2. [Using Slang to write PyTorch kernels](../deprecated/a1-02-slangpy.md)
 3. [Obfuscation](a1-03-obfuscation.md)
 4. [Interoperation with target-specific code](a1-04-interop.md)
 5. [Uniformity Analysis](a1-05-uniformity.md)
@@ -20,7 +20,7 @@ In this chapter:
 :hidden:
 
 Handling Matrix Layout Differences on Different Platforms <a1-01-matrix-layout>
-Using Slang to Write PyTorch Kernels <a1-02-slangpy>
+Using Slang to Write PyTorch Kernels <../deprecated/a1-02-slangpy>
 Obfuscation <a1-03-obfuscation>
 Interoperation with Target-Specific Code <a1-04-interop>
 Uniformity Analysis <a1-05-uniformity>
diff --git a/docs/user-guide/a2-01-spirv-target-specific.md b/docs/user-guide/a2-01-spirv-target-specific.md
index 6d73199e0..2ea4372d9 100644
--- a/docs/user-guide/a2-01-spirv-target-specific.md
+++ b/docs/user-guide/a2-01-spirv-target-specific.md
@@ -246,7 +246,7 @@ To generate a valid SPIR-V with multiple entry points, use `-fvk-use-entrypoint-
 Global memory pointers
 ------------------------------
 
-Slang supports global memory pointers when targeting SPIRV. See [an example and explanation](convenience-features.html#pointers-limited).
+Slang supports global memory pointers when targeting SPIRV. See [an example and explanation](03-convenience-features.html#pointers-limited).
 
 `float4*` in user code will be translated to a pointer in PhysicalStorageBuffer storage class in SPIRV.
 When a slang module uses a pointer type, the resulting SPIRV will be using the SpvAddressingModelPhysicalStorageBuffer64 addressing mode. Modules without use of pointers will use SpvAddressingModelLogical addressing mode.
diff --git a/docs/user-guide/a3-02-reference-capability-atoms.md b/docs/user-guide/a3-02-reference-capability-atoms.md
index ea3e5952a..b6aa7aba2 100644
--- a/docs/user-guide/a3-02-reference-capability-atoms.md
+++ b/docs/user-guide/a3-02-reference-capability-atoms.md
@@ -7,12 +7,12 @@ Capability Atoms
 
 ### Sections:
 
-1. [Targets](#Targets)
-2. [Stages](#Stages)
-3. [Versions](#Versions)
-4. [Extensions](#Extensions)
-5. [Compound Capabilities](#Compound-Capabilities)
-6. [Other](#Other)
+1. [Targets](#targets)
+2. [Stages](#stages)
+3. [Versions](#versions)
+4. [Extensions](#extensions)
+5. [Compound Capabilities](#compound-capabilities)
+6. [Other](#other)
 
 Targets
 ----------------------
diff --git a/source/slang/slang-doc-markdown-writer.cpp b/source/slang/slang-doc-markdown-writer.cpp
index ae0ddc1a5..540f0c2e5 100644
--- a/source/slang/slang-doc-markdown-writer.cpp
+++ b/source/slang/slang-doc-markdown-writer.cpp
@@ -2166,6 +2166,7 @@ String DocMarkdownWriter::translateToMarkdownWithLinks(String text, bool strictC
                 sb.append(Path::getPathWithoutExt(Path::getRelativePath(
                     Path::getParentDirectory(m_currentPage->path),
                     page->path)));
+                sb.append(".html");
                 if (sectionName.getLength())
                     sb << "#" << sectionName;
                 sb.append(")");