Skip to content

version-snapshot guides alongside API reference, fix index.md links, …#178

Merged
petesramek merged 1 commit intodevelop/1.0from
preview/1.0
Apr 4, 2026
Merged

version-snapshot guides alongside API reference, fix index.md links, …#178
petesramek merged 1 commit intodevelop/1.0from
preview/1.0

Conversation

@petesramek
Copy link
Copy Markdown
Owner

…add released versions table (#175)

Summary

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.

Changes

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

docs-versioning/public/version-switcher.js

  • Fixed the fallback navigation branch to resolve the site root via the docfx:rel meta tag and navigate to /{ver}/PolylineAlgorithm.html instead of the bare /{ver}/ folder

…add released versions table (#175)

## Summary

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.

## Changes

### 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

### `docs-versioning/public/version-switcher.js`
- Fixed the fallback navigation branch to resolve the site root via the
`docfx:rel` meta tag and navigate to `/{ver}/PolylineAlgorithm.html`
instead of the bare `/{ver}/` folder
@petesramek petesramek merged commit d8340a7 into develop/1.0 Apr 4, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant