[TASK] Correct the .gitignore comment for schema/reference/ after the schema docs move

Type

Task

Scope

Multi-theme or Platform

Skillset

engineering

Description

What

.gitignore lines 7-9 read:

# Scratch output of the schema doc generator: written by add-schema-version and
# by the schema repo's PR preview workflow (SCHEMA_PREVIEW=true). See README.
schema/reference/

The path and the entry are correct and should stay. The second half of the comment is not currently true.

Why the entry stays

schema/reference/ is read by exactly one thing: a SCHEMA_PREVIEW=true build, where the schema docs instance builds current from schema/ (docusaurus.config.js lines 55-59) and sidebars-schema.js line 10 autogenerates from dirName: 'reference'. Verified on a clean checkout at fccbbe22:

• npm run build — succeeds, never creates schema/reference/
• SCHEMA_PREVIEW=true npm run docusaurus -- build — fails on broken links to /schema/reference/* when the directory is absent

That generated tree is a rolling build of an unreleased schema branch, so it must not be committed next to the released snapshots in schema_versioned_docs/. scripts/add-schema-version.mjs also writes there, and cleans up in a finally (lines 110-112), so it only leaves debris if the run is interrupted.

What is wrong

The schema repo's PR preview workflow does not write to schema/reference/ today. It still writes to docs/schema/reference — the path used before #512 moved the schema instance out of docs/. Filed as OvertureMaps/schema#755.

Worth noting for whoever fixes that: schema/reference/ is root-anchored, so it does not match docs/schema/reference/. Output at the old path shows up as untracked (?? docs/schema/), confirmed with git check-ignore -v --no-index.

Also stale from the same move: sidebars-schema.js line 2 still describes the instance as "docs/schema and schema_versioned_docs/".

Acceptance criteria

• The .gitignore comment describes only what actually writes to schema/reference/, or is corrected in step with OvertureMaps/schema#755
• sidebars-schema.js docstring refers to schema/ rather than docs/schema
• The schema/reference/ entry itself remains

Start with the referenced lines in .gitignore and sidebars-schema.js, then check OvertureMaps/schema#755 to confirm the preview workflow's path. Keep the schema/reference/ entry, make its comment accurate, and update the sidebars-schema.js docstring to refer to schema/. Verify the diff and the stated acceptance criteria.