feat: version-snapshot guides alongside API reference, fix index.md links, add released versions table (#174)

Previously, versioned folders contained only API reference YAMLs while
guide pages were global (unversioned). The root `index.md` had entirely
broken links. The version switcher navigated to a bare `/{ver}/` folder
that has no `index.html`, causing 404s on GitHub Pages.

## Workflow (`publish-documentation.yml`)

- **Guide snapshot**: copies `api-reference/guide/` into
`api-reference/{ver}/guide/` immediately after API metadata generation,
so each version folder contains a full snapshot of both guide and API
reference
- **DocFX version groups**: each group now registers two content entries
— API YAMLs (`*.yml`) and guide pages (`guide/*.{md,yml}`) — producing
`_docs/{ver}/` and `_docs/{ver}/guide/` in the build output
- **Global TOC**: `Guide` nav link now points to
`{latest}/guide/introduction.html` instead of the unversioned `guide/`
- **index.md injection**: a single step builds the released versions
table and substitutes both `{version}` and `{versions_section}`
placeholders before `docfx build` runs (no committed artefacts)

## `api-reference/api-reference.json`

Removed `guide/*.{md,yml}` from the global content entry — guide pages
now exist only within versioned groups.

## `api-reference/index.md`

Replaced broken links with `{version}`-placeholder paths resolved at
build time. Added a `{versions_section}` placeholder that the workflow
expands into a full released-versions table, e.g.:

| Version | Guide | API Reference |
|---------|-------|---------------|
| v2.0 (latest) | [Guide](2.0/guide/introduction.html) | [API
Reference](2.0/PolylineAlgorithm.html) |
| v1.0 | [Guide](1.0/guide/introduction.html) | [API
Reference](1.0/PolylineAlgorithm.html) |

## `docs-versioning/public/version-switcher.js`

Fixed the fallback navigation branch (triggered when the user is not
inside a versioned path) to resolve the site root via the `docfx:rel`
meta tag and navigate to `/{ver}/PolylineAlgorithm.html` instead of the
bare `/{ver}/` folder.

Author: Copilot

.github/workflows/publish-documentation.yml

@@ -91,6 +91,11 @@ jobs:
           docfx metadata assembly-metadata.json
           mv temp ${{ env.friendly-version }}
 
+      - name: 'Snapshot guide for v${{ env.friendly-version }}'
+        shell: bash
+        run: |
+          cp -r api-reference/guide api-reference/${{ env.friendly-version }}/guide
+
       - name: 'Discover all versions'
         id: discover-versions
         shell: bash
@@ -116,7 +121,10 @@ jobs:
           cp api-reference/api-reference.json /tmp/api-reference.json
           for ver in $(echo "${{ steps.discover-versions.outputs.versions }}" | tr ',' ' '); do
             jq --arg ver "$ver" --arg group "v${ver}" \
-               '.build.content += [{"dest": "", "files": ["*.yml"], "group": $group, "src": $ver, "rootTocPath": "~/toc.html"}] |
+               '.build.content += [
+                  {"dest": "",      "files": ["*.yml"],          "group": $group, "src": $ver,               "rootTocPath": "~/toc.html"},
+                  {"dest": "guide", "files": ["*.{md,yml}"], "group": $group, "src": ($ver + "/guide"), "rootTocPath": "~/toc.html"}
+               ] |
                 .build.groups = (.build.groups // {}) |
                 .build.groups[$group] = {"dest": $ver}' \
                /tmp/api-reference.json > /tmp/api-reference-new.json
@@ -131,7 +139,7 @@ jobs:
           {
             echo "### YamlMime:TableOfContent"
             echo "- name: Guide"
-            echo "  href: guide/"
+            echo "  href: ${latest}/guide/introduction.html"
             echo "- name: Reference"
             echo "  dropdown: true"
             echo "  items:"
@@ -145,6 +153,29 @@ jobs:
             done
           } > api-reference/toc.yml
 
+      - name: 'Inject latest version and released versions table into index.md'
+        shell: bash
+        run: |
+          latest="${{ steps.discover-versions.outputs.latest }}"
+          {
+            echo "## Released Versions"
+            echo ""
+            echo "| Version | Guide | API Reference |"
+            echo "|---------|-------|---------------|"
+            for ver in $(echo "${{ steps.discover-versions.outputs.versions }}" | tr ',' '\n' | sort -Vr); do
+              if [ "$ver" = "$latest" ]; then
+                label="v${ver} (latest)"
+              else
+                label="v${ver}"
+              fi
+              echo "| ${label} | [Guide](${ver}/guide/introduction.html) | [API Reference](${ver}/PolylineAlgorithm.html) |"
+            done
+          } > /tmp/versions_section.md
+          awk '/{versions_section}/{while((getline line < "/tmp/versions_section.md") > 0) print line; close("/tmp/versions_section.md"); next} {print}' \
+            api-reference/index.md > /tmp/index.md
+          mv /tmp/index.md api-reference/index.md
+          sed -i "s|{version}|${latest}|g" api-reference/index.md
+
       - name: 'Build documentation'
         shell: bash
         run: docfx build api-reference/api-reference.json

api-reference/api-reference.json

@@ -8,8 +8,7 @@
       {
         "files": [
           "index.md",
-          "toc.yml",
-          "guide/*.{md,yml}"
+          "toc.yml"
         ],
         "exclude": [
           "_docs/**"

api-reference/docs-versioning/public/version-switcher.js

@@ -53,7 +53,8 @@
           '/' + targetVersion + '/'
         );
       } else {
-        newPathname = window.location.pathname.replace(/\/$/, '') + '/' + targetVersion + '/';
+        var siteRootPath = new URL(getSiteRoot(), window.location.href).pathname.replace(/\/$/, '');
+        newPathname = siteRootPath + '/' + targetVersion + '/PolylineAlgorithm.html';
       }
 
       window.location.pathname = newPathname;

api-reference/index.md

@@ -1,18 +1,20 @@
 # PolylineAlgorithm API Reference
 
 Welcome! This documentation provides guides, configuration options, examples, and FAQs for the PolylineAlgorithm library.  
-For detailed class and method docs, see the [auto-generated API documentation](https://petesramek.github.io/polyline-algorithm-csharp/).
+For detailed class and method docs, see the versioned [API Reference]({version}/PolylineAlgorithm.html).
 
 ## Contents
 
-- [Quick Start Guide](./guide.md)
-- [Configuration Options](./configuration.md)
-- [Advanced Usage](./advanced.md)
-- [Examples](./examples.md)
-- [FAQ](./faq.md)
+- [Introduction]({version}/guide/introduction.html)
+- [Getting Started]({version}/guide/getting-started.html)
+- [Configuration Options]({version}/guide/configuration.html)
+- [Advanced Scenarios]({version}/guide/advanced-scenarios.html)
+- [Samples]({version}/guide/sample.html)
+- [FAQ]({version}/guide/faq.html)
+
+{versions_section}
 
 ## Links
 
-- [API Reference Site](https://petesramek.github.io/polyline-algorithm-csharp/)
-- [Contributing Guidelines](../CONTRIBUTING.md)
-- [Changelog](./changelog.md) (if provided)
+- [API Reference]({version}/PolylineAlgorithm.html)
+- [Contributing Guidelines](https://github.com/petesramek/polyline-algorithm-csharp/blob/main/CONTRIBUTING.md)