Skip to content

docs: VitePress with full vi/en i18n + quiz, exam library, URL shortener guides - #2

Merged
behitek merged 11 commits into
masterfrom
docs/vitepress-platform
Sep 19, 2026
Merged

behitek merged 11 commits into
masterfrom
docs/vitepress-platform

Conversation

@behitek

@behitek behitek commented Sep 19, 2026

Copy link
Copy Markdown
Member

Summary

Moves the docs from Docsify to VitePress with full Vietnamese and English support, and adds how-to guides for features that had no docs. plans/ (local working notes, e.g. the refactor plan) is now gitignored.

Platform

  • Docsify → VitePress. The Vietnamese pages move from docs/ to src/ with the same URLs and keep their git history.
  • Old Docsify links redirect: /#/site/x?id=y/site/x#y.
  • Built-in search per language, Mermaid diagrams, LCOJ logo and brand color, dark mode.
  • Every page has "Edit on GitHub" and "last updated". The footer credits DMOJ/VNOJ and links support (GitHub Issues · behitek.com · luyencode.net contact).
  • Branding and SEO like luyencode.net: the LCOJ favicon set (replacing the inherited VNOI icon), theme-color, Open Graph and Twitter cards with og_logo.png. Each page gets a canonical URL, vi↔en hreflang alternates, its own title and description, and there is a sitemap.xml.
  • GitHub Actions deploy to Pages on push to master. CNAME (docs.luyencode.net) is kept.

i18n

  • Vietnamese stays at /, and English is at /en/, with a language switcher.
  • All 31 pages exist in both languages. Commands and config are not translated. UI labels match the app's own English strings.
  • npm run check:locales runs in CI and fails if a page exists in only one language.

New guides (vi + en, written from the lcoj-site code, with diagrams)

Page For
features/quiz: taking a quiz Students: finding quizzes, integrity monitoring, question types, autosave, time limit + 30 s grace, result modes, ranking, FAQ
features/quiz_authoring: creating quizzes Teachers: permissions, question bank, grading strategies (worked example), exact XLSX/JSON import format, quiz settings, clone, attempts/violations review, regrade
features/library: exam library Readers (browse, flipbook) and admins (add exams, PDF storage, troubleshooting)
features/url_shortener: URL shortener Staff (create links), admins (permissions), operators (dedicated short domain)

Fixes

  • The dev server rendered a blank page because of Mermaid 11.17's CommonJS fastdom dependency. Mermaid is now pre-bundled.
  • Nested code blocks broke the layout of managing_problems and management_commands (both languages).
  • - [ ] checklists now render as checkboxes.

Not in this PR

  • The existing pages were translated as-is, so both languages still carry the same outdated facts (env example, ports, permission descriptions, generator example, …). They get corrected together in Phase 1; tracked in the local refactor plan.
  • lcoj-site bugs found while writing: the URL shortener's redirect isn't enabled, so short links 404; quiz grading edge cases; several wrong Vietnamese quiz labels. They are tracked in the local refactor plan for the app backlog.
  • No screenshots, by decision. Visuals are diagrams, tables and callouts only.

⚠️ Before merging

This PR removes docs/, which the current Pages source serves from.

  1. Settings → Pages → Source → GitHub Actions
  2. Merge right away. The first deploy takes about a minute.

Test plan

  • npm run check:locales: 31 pages in sync
  • npm run build: clean, no dead links; an extra scan of the built HTML found 0 broken #anchor links
  • Chrome: all 8 feature pages (vi + en) render, all Mermaid diagrams draw with no syntax errors, no JS errors; legacy /#/ redirects work in dev and preview
  • CI green on this branch
  • After merge: https://docs.luyencode.net and https://docs.luyencode.net/en/ load, and an old /#/... link redirects

🤖 Generated with Claude Code

behitek and others added 9 commits March 20, 2026 22:14
- Move content from docs/ to src/ (paths unchanged), vi as root locale, en placeholder at /en/
- Sidebar/nav per locale, local search, Mermaid, LCOJ logo and brand color
- Redirect legacy Docsify hash links (/#/site/x?id=y -> /site/x#y)
- Deploy to GitHub Pages via Actions; PRs build-only (dead-link check)
- Add refactor plan: plans/2026-09-19-docs-i18n-refactor-design.md

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mermaid 11.17 depends on CommonJS fastdom, which vitepress-plugin-mermaid
doesn't pre-bundle; in `vitepress dev` the page failed with a missing
default export and rendered blank. Production build was unaffected.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…uides

- Translate all 26 existing pages to English under src/en/ (same structure,
  commands untouched, UI labels match the app's English strings)
- New bilingual how-to pages (verified against lcoj-site code), with diagrams:
  features/quiz, features/quiz_authoring, features/library, features/url_shortener
- English sidebar/nav/home; "Features" section in both locales
- scripts/check-locales.mjs + CI step: fail if a page exists in only one locale
- Render "- [ ]" checklists as checkboxes (markdown-it-task-lists)
- Fix nested code fences that broke rendering in managing_problems and
  management_commands (both locales)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Plan: phase status, decision to use diagrams instead of screenshots,
  list of doc errors and lcoj-site bugs found while translating
- README: every page needs vi + en twins, check:locales, no screenshots

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@behitek behitek changed the title docs: migrate from Docsify to VitePress with vi/en locales docs: VitePress with full vi/en i18n + quiz, exam library, URL shortener guides Sep 19, 2026
behitek and others added 2 commits September 19, 2026 11:23
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Replace the inherited VNOI favicon with the LCOJ icon set from
  lcoj-site resources/icons (ico, 16/32/96, apple-touch, android-chrome)
- Add theme-color, Open Graph and Twitter card tags with og_logo.png,
  same as luyencode.net
- Per page: canonical URL, og:url, og:locale, vi/en hreflang alternates,
  title and description (first paragraph when no frontmatter description)
- Home pages get proper titles/descriptions; generate sitemap.xml

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@behitek
behitek merged commit e5d5727 into master Sep 19, 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.

1 participant