Update documentation site navigation

[koriym]

Summary

• Consolidate the README documentation entry point and add the Ray.MediaQuery logo.
• Rework the docs home page with language switching, localized cards, and ecosystem links.
• Add English tutorial, Japanese manual updates, BDR docs pages, and fix the readonly lazy-loading example.

Validation

• git diff c4ada94^..c4ada94 --check
• jekyll build -s docs -d /tmp/ray-mediaquery-site

Summary by CodeRabbit

Release Notes

• New Features

  • Bilingual language switcher added to documentation homepage (English/Japanese)
  • Comprehensive BDR Pattern documentation guides with practical implementation examples
  • Ray.MediaQuery 1.1 hands-on tutorial featuring SQLite blog service example

• Documentation

  • Updated manual with expanded feature descriptions, result handling, and DML/SELECT operations
  • Reorganized documentation structure and navigation links
  • Added BEAR.Sunday integration and migration guidance sections

• Style

  • Enhanced website typography, layout, and responsive design improvements

[koriym]

@coderabbitai review

This PR updates the documentation site navigation and language flow. Please review the docs homepage language switching, README documentation entry point, added BDR docs pages, English tutorial, Japanese manual updates, and the readonly lazy-loading example fix.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Get PR details and list of changed files
gh pr view 100 --repo ray-di/Ray.MediaQuery --json title,body,files,headRefName

echo "=== Changed files ==="
gh pr diff 100 --repo ray-di/Ray.MediaQuery --name-only

Length of output: 2379

---

🏁 Script executed:

#!/bin/bash
# Get the full diff for the PR
gh pr diff 100 --repo ray-di/Ray.MediaQuery

Length of output: 144501

---

🏁 Script executed:

#!/bin/bash
echo "=== Check for .note CSS class usage ==="
rg '\.note\b|class="note"' docs/ --type=html --type=css -n

echo ""
echo "=== Check remaining links pointing to /tutorial/ that may need /tutorial/ja/ ==="
rg '/tutorial/' docs/ --include='*.md' --include='*.html' --include='*.yml' -n

echo ""
echo "=== Check for any remaining 'Feature Reference' text in docs ==="
rg -i 'feature.reference' docs/ -n

echo ""
echo "=== Check if the old /tutorial/ permalink exists anywhere now ==="
rg 'permalink.*tutorial' docs/ --include='*.md' --include='*.html' -n

echo ""
echo "=== Check for broken relative links in bdr-pattern docs ==="
rg 'relative_url' docs/bdr-pattern.md docs/bdr-pattern-ja.md -n

Length of output: 2308

---

🏁 Script executed:

#!/bin/bash
echo "=== Check remaining links pointing to /tutorial/ ==="
rg '/tutorial/' docs/ -n --type md --type html

echo ""
echo "=== Check permalinks for tutorial pages ==="
rg 'permalink.*tutorial' docs/ -n --type md --type html

echo ""
echo "=== Check for stale links in root-level BDR_PATTERN files ==="
rg '/tutorial/' BDR_PATTERN.md BDR_PATTERN-ja.md README.md -n

echo ""
echo "=== Check the tutorial/README.ja.md link to English tutorial ==="
grep -n 'tutorial' docs/tutorial/README.ja.md | head -20

echo ""
echo "=== Verify docs/index.html Japanese section has no lead paragraph ==="
grep -n 'lead\|data-lang="ja"' docs/index.html | head -20

echo ""
echo "=== Check any links in docs still pointing to old Feature Reference ==="
rg 'Feature Reference|feature.reference' docs/ -n --type md --type html

echo ""
echo "=== Check docs/bdr-pattern.md and bdr-pattern-ja.md have correct permalinks ==="
grep 'permalink' docs/bdr-pattern.md docs/bdr-pattern-ja.md

Length of output: 8585

---

---

@koriym: Here is a thorough review of the PR.

---

Overall

The PR is well-structured. The language-switching homepage, consolidated docs entry point, new BDR pages, English tutorial, Japanese manual, and the readonly lazy-loading fix all look correct. A few items below are worth addressing before merge.

---

1. readonly lazy-loading fix — ✅ Correct

The old code in BDR_PATTERN.md and BDR_PATTERN-ja.md used ??= on a readonly property:

final readonly class ProductDomainObject
{
    private ?float $currentPrice = null;

    public function getCurrentPrice(): float
    {
        return $this->currentPrice ??= $this->priceService->getPrice($this->id);
    }
}

This is a PHP fatal: readonly properties cannot be assigned after initialisation, so ??= mutates illegally. The fix correctly delegates caching responsibility to PriceProvider, which is also architecturally consistent with the BDR pattern's principle of keeping readonly objects as pure snapshots.

---

2. Old Japanese tutorial permalink now silently resolves to English (Medium)

Before this PR: /tutorial/ → Japanese tutorial (README.ja.md)
After this PR: /tutorial/ → English tutorial (README.md), Japanese → /tutorial/ja/

Any existing bookmarks or external links to /tutorial/ will now silently serve the English tutorial rather than the Japanese one. Since GitHub Pages doesn't support server-side redirects, a no-content redirect stub would cover this:

---
layout: redirect
redirect_to: /Ray.MediaQuery/tutorial/ja/
permalink: /tutorial/ja-old/
---

Or a simpler approach — add a meta-refresh redirect page at the old path. Even a brief note in the "Breaking Changes" section of CHANGELOG.md would help users who hit this.

---

3. Stale description text in docs/tutorial/README.md Line 1749 (Low)

The "Next Reading" section says:

- [Manual 日本語版](https://ray-di.github.io/Ray.MediaQuery/reference/) - advanced feature reference, including ...

Since /reference/ is now the Japanese manual, the description "advanced feature reference" is stale. Suggested change:

- [Manual 日本語版](https://ray-di.github.io/Ray.MediaQuery/reference/) — Japanese manual covering installation, module setup, result mapping, pagination, and more

---

4. Missing lead paragraph in Japanese hero (Low)

docs/index.html — the English data-lang="en" block has a <p class="lead"> but the Japanese data-lang="ja" block does not:

<div data-lang="en" lang="en">
  <p class="product-label">Ray.MediaQuery</p>
  <h1>Interface-Driven SQL for PHP</h1>
  <p class="lead">SQL speaks infrastructure. Types express the domain. PHP interfaces bridge them.</p>
</div>
<div data-lang="ja" lang="ja">
  <p class="product-label">Ray.MediaQuery</p>
  <h1>Interface-Driven SQL for PHP</h1>
  <!-- no lead paragraph -->
</div>

The Japanese hero has noticeably less content than the English one. Consider adding a Japanese equivalent for <p class="lead">, e.g.:

<p class="lead">SQL はインフラを語り、型はドメインを表す。PHP インターフェイスがその橋渡しをする。</p>

---

5. No-JS behaviour (Informational)

The language switching relies entirely on JavaScript. When JS is disabled, data-doc-lang is never set on <html>, so the CSS rule:

html[data-doc-lang="en"] [data-lang="ja"],
html[data-doc-lang="ja"] [data-lang="en"] { display: none !important; }

…never fires, and both language sections are simultaneously visible. This is a functional degraded experience (all content readable), so it is not a blocker, but it may look odd. A CSS-only default can be set as a fallback:

/* Default: hide JA sections; JS will override to the correct lang */
[data-lang="ja"] { display: none; }

Then JS removes the fallback for the selected language. Alternatively, a <noscript> note is sufficient.

---

6. CHANGELOG wording (Nit)

The CHANGELOG entry reads:

Japanese manual covering installation, module setup... (docs/reference.md)

docs/reference.md already existed as an English Feature Reference; this PR re-writes it in Japanese. Saying "added" is slightly misleading. A small clarification:

- - Japanese manual covering installation, module setup...
+ - Replaced `docs/reference.md` English Feature Reference with a full Japanese manual covering...

---

Summary

#	File	Severity	Status
2	docs/tutorial/README.ja.md permalink change	Medium	Suggest redirect stub
3	docs/tutorial/README.md Line 1749 description	Low	Easy fix
4	docs/index.html Japanese hero lead	Low	Polish
5	No-JS both-language visibility	Info	Optional
6	CHANGELOG.md wording	Nit	Optional

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR comprehensively restructures Ray.MediaQuery documentation to emphasize the Business Domain Repository pattern as a read-side query object architecture. It adds two new full implementation guides (English and Japanese), introduces a hands-on tutorial, implements bilingual site support with language switching, and updates navigation/landing pages.

Changes

Documentation & Site Restructuring

Layer / File(s)	Summary
BDR Pattern Conceptual Refinement BDR_PATTERN.md, BDR_PATTERN-ja.md	Both English and Japanese versions are updated to clarify that domain objects are read-side query/projection objects. The predicate method canProcess() is renamed to canShowProcessAction() to emphasize presentation intent. FAQ sections are substantially rewritten to address CQRS, explicit write paths, and how read-side objects should not be persisted directly. External API integration examples are refactored to delegate to injected PriceProvider services, and new BEAR.Sunday integration sections are added.
Comprehensive BDR Implementation Guides docs/bdr-pattern.md, docs/bdr-pattern-ja.md	Two new comprehensive guides (683 and 733 lines respectively) introduce the full BDR pattern: executive summary, motivation, immutable read-side objects, repository interface definition, SQL projection examples, domain factories with transformation logic, rich domain objects with read-side behavior, three-layer testing strategy (SQL/factory/domain object), practical patterns (polymorphism, external APIs, caching), migration guidance from controller logic, AI-era transparency principles, CQRS FAQ, and BEAR.Sunday/Async integration guidance.
Hands-on Tutorial and Reference Manual docs/tutorial/README.md, docs/reference.md, docs/tutorial/README.ja.md	A complete hands-on tutorial (1756 lines, 14 chapters plus appendix) walks through building a SQLite blog service using Ray.MediaQuery 1.1 features: typed DML/SELECT results, factory hydration, pagination, and testing with fakes. The reference documentation is converted from English feature reference to a comprehensive Japanese manual covering installation, setup, SQL files, configuration, result hydration, DML operations, factory patterns, parameter handling, pagination, and direct SQL execution, with extensive examples.
Bilingual Site Infrastructure and Styling docs/_config.yml, docs/_layouts/default.html, docs/assets/css/style.css	Jekyll configuration switches the default language from Japanese to English. The default layout template now conditionally applies a page-home CSS class for the home page. CSS is significantly expanded (from 12 to 107 lines of net additions) to support language-aware content hiding via data-doc-lang/data-lang attributes, language-switcher component styling with button states and focus outlines, responsive hero/header typography and logo sizing (including mobile max-width: 760px breakpoint), updated card grid column strategy, and an .actions flex container for button groups. The .note styling block is removed.
Navigation and Landing Page Updates README.md, CHANGELOG.md, docs/index.html, docs/ja/index.md	README adds Ray.MediaQuery logo and condenses documentation section to "Documentation Home" and "Demo Application" links. CHANGELOG reflects the new English hands-on tutorial and Japanese manual. The Japanese index page expands from a single "MediaQuery" link to three: Manual, Hands-on Tutorial, and Old Memo. The landing page (docs/index.html) is fully rebuilt with bilingual support: a localStorage-backed language switcher (with en/ja toggle buttons), bilingual hero copy with language-specific wrappers, and revised card navigation for both languages (Manual, Hands-on Tutorial, BDR Pattern, FAQ, Ecosystem) with updated link targets and Japanese "Async recipe" reference.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ray-di/Ray.MediaQuery#94: Related documentation updates to BEAR.Sunday and BEAR.Async integration sections in BDR pattern guides.

Poem

📚 A rabbit hops through docs so bright,
Bilingual guides, a wondrous sight!
From BDR patterns, read-side clean,
To tutorials—the best we've seen! 🐰✨
Domain objects query left and right,
This documentation shines so light!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective of the pull request—reorganizing documentation site navigation, language switching, and localized documentation structure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-home-localization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}