Skip to content

Fix local preview guidance for course chapters#1185

Merged
stevhliu merged 1 commit intohuggingface:mainfrom
junepil:fix/preview-debug
Feb 17, 2026
Merged

Fix local preview guidance for course chapters#1185
stevhliu merged 1 commit intohuggingface:mainfrom
junepil:fix/preview-debug

Conversation

@junepil
Copy link
Contributor

@junepil junepil commented Feb 15, 2026

Background

When contributors preview translated course content locally, doc-builder preview may start successfully but still return runtime 404 for valid routes.

Root Cause

The issue came from a dependency/version skew in the local tooling:

  • Python package: hf-doc-builder installed from PyPI (v0.5.0) which generates .mdx file for preview.
  • Frontend template: cached doc-builder kit from a newer revision which requires +page.svelte file per path.

Because of this mismatch, route generation behavior was inconsistent and local preview could boot while serving unresolved routes as 404.

What Changed

  1. Updated contributor instructions in README.md to:
    • use a clean virtual environment;
    • install hf-doc-builder from the current GitHub source;
    • run preview with explicit --language LANG-ID.
  2. Added a troubleshooting section for preview-time 404 that clearly points to re-installing hf-doc-builder and restarting preview.

Why This Helps

Contributors now get deterministic setup steps that keep the Python CLI and SvelteKit template in sync, which prevents route-generation mismatch and avoids false-negative 404 previews.
image

Verification Notes

  • Confirmed translated routes render after aligning doc-builder dependency source.
  • Confirmed chapter routes behavior is stable when preview is started with explicit language flag.

Things To Note

  • Currently, the root path isn't configured properly due to the absence of root path document file.

References

@HuggingFaceDocBuilderDev

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@junepil
Copy link
Contributor Author

junepil commented Feb 15, 2026

@stevhliu If you have time please take a look, have a wonderful day 😎

@stevhliu
Copy link
Member

nice, thanks for this! 🤗

@stevhliu stevhliu merged commit 5739145 into huggingface:main Feb 17, 2026
2 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.

3 participants

Comments