Add Demos page to manual

[koriym]

Summary

• Add demos.md for English and Japanese manual
• Explain Order Processing demo with Diamond Metamorphosis pattern
• Add Demos link to navigation header (language-aware)

Content

• Key concepts: Moment, Reason, Final
• Philosophical foundations table
• Links to demo site, source code, and ALPS profile

Test plan

• Verify Jekyll builds successfully
• Check English page renders correctly
• Check Japanese page renders correctly
• Verify navigation link switches language appropriately

Summary by CodeRabbit

• New Features

  • Added "Demos" navigation link to the header that automatically routes to the appropriate language version.

• Documentation

  • Added comprehensive Demos documentation in English and Japanese, featuring Order Processing Demo examples and conceptual guides.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@koriym has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 5 minutes and 38 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 8b164d1 and 3eb859e.

📒 Files selected for processing (3)

• _includes/manuals/1.0/header.html
• manuals/1.0/en/demos.md
• manuals/1.0/ja/demos.md

📝 Walkthrough

Walkthrough

Added a "Demos" navigation item to the documentation header with locale-aware routing that points to Japanese or English demo pages based on layout. Created two corresponding demo documentation pages introducing order processing workflows using the Diamond Metamorphosis pattern with code examples and architectural concepts.

Changes

Cohort / File(s)	Summary
Navigation Enhancement _includes/manuals/1.0/header.html	Added conditional "Demos" navbar link; routes to /manuals/1.0/ja/demos/ for docs-ja layout, otherwise to /manuals/1.0/en/demos/
Documentation Content manuals/1.0/en/demos.md, manuals/1.0/ja/demos.md	New demo pages (English and Japanese) documenting Order Processing Demo with Diamond Metamorphosis pattern, including ASCII flow diagrams, PHP code examples (PaymentCompleted, PaymentGateway, OrderConfirmed), Philosophical Foundations table, and external resource links

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A whisker-twitch and the Demos appear,
Threading through docs in languages clear!
English and Japanese, side by side,
With diamonds and patterns and payment-flows wide,
The header now hops with a navigational cheer,
Framework foundations grow stronger each year! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Demos page to manual' directly and clearly summarizes the main change: adding documentation pages for demos in both English and Japanese, plus a navigation link.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

---

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.}

[claude]

Code Review: Add Demos Page to Manual

Summary

This PR adds a new Demos page with bilingual content (English/Japanese) and navigation integration. The changes are well-structured and follow the existing Jekyll patterns.

✅ Strengths

1. Consistent Structure: Follows existing manual page patterns with proper frontmatter, layout templates, and permalinks
2. Bilingual Support: Both English and Japanese versions are properly implemented with correct layouts (docs-en and docs-ja)
3. Content Quality: Technical content accurately represents Be Framework concepts with clear examples and philosophical foundations
4. Navigation Integration: Language-aware navigation link correctly switches between /en/ and /ja/ based on current page layout

🔍 Issues Found

1. Navigation Inconsistency (Minor)

Location: _includes/manuals/1.0/header.html:30-32

The Demos link uses conditional logic for language switching, but it doesn't set the active class when on the demos page.

Current:

<li class="nav-item">
    <a class="nav-link" href="{% if page.layout == 'docs-ja' %}/manuals/1.0/ja/demos.html{% else %}/manuals/1.0/en/demos.html{% endif %}">Demos</a>
</li>

Suggested:

<li class="nav-item">
    <a class="nav-link {% if page.url contains '/demos.html' %}active{% endif %}" href="{% if page.layout == 'docs-ja' %}/manuals/1.0/ja/demos.html{% else %}/manuals/1.0/en/demos.html{% endif %}">Demos</a>
</li>

This would highlight the Demos nav item when viewing the demos page, consistent with how Manual and Home work.

2. Missing from Sidebar Navigation

Location: _includes/manuals/1.0/en/contents.html and ja/contents.html

The demos page won't appear in the left sidebar navigation because the contents.html template uses a Jekyll loop that automatically discovers pages:

{% assign en_pages = site.pages | where: "layout", "docs-en" | where: "category", "Manual" | sort: "path" %}

The demos page should appear automatically IF it has category: Manual in frontmatter (which it does), so it should work. However, verify this during testing.

3. Content Issues

a) Missing Closing Backtick in Code Block (en/demos.md:48)

The PaymentCompleted constructor has an unclosed property:

$this->capture = $gateway->authorize($cardNumber, $amount);

This should have a closing brace and proper visibility declaration.

Note: Looking at the code more carefully, this appears to be a readonly class property being set, which is valid in PHP 8.1+. However, the example is incomplete - the $capture property isn't declared in the class definition shown. Consider showing the full class or adding a comment.

b) Table Alignment (Both files)

The philosophical foundations table would benefit from consistent column widths. Currently readable but could be improved for better markdown rendering.

4. External Links Not Verified

Security/Availability: The PR includes links to:

• https://be-framework.github.io/demos/
• https://github.com/be-framework/demos/tree/1.x/demos/order-processing
• https://be-framework.github.io/demos/alps.html

These external URLs should be verified to ensure they exist and are accessible before merging.

📋 Best Practices & Conventions

✅ Followed Correctly:

• Proper Jekyll frontmatter with required fields
• Correct layout templates for each language
• Consistent permalink structure
• Proper use of category: Manual
• Code examples use PHP (consistent with framework)
• Proper markdown formatting with code fences

🔒 Security Considerations

No security issues identified. The PR only adds static markdown content.

⚡ Performance Considerations

No performance concerns. Jekyll will build these as static HTML pages.

🧪 Testing Recommendations

Based on the test plan in the PR description, here's what to verify:

Local Testing Commands

# Build and serve locally
./bin/serve.sh

# Then manually verify:
# 1. English page: http://localhost:4000/manuals/1.0/en/demos.html
# 2. Japanese page: http://localhost:4000/manuals/1.0/ja/demos.html
# 3. Navigation link switches language when switching between en/ja pages
# 4. Demos link in header appears on all pages
# 5. "Demos" appears in sidebar navigation (if expected)
# 6. Language switcher works between en/ja demos pages

Build Verification

# Check for Jekyll build errors
docker compose up

# Look for any warnings or errors in output
# Verify _site/manuals/1.0/en/demos.html and ja version are generated

📝 Recommended Changes Before Merge

1. Add active class logic to Demos nav link (see Issue Add philosophical depth to chapters 1-3 with Eastern and Western philosophy integration #1 above)
2. Verify external links are accessible
3. Consider adding a comment to the PaymentCompleted code example explaining the $capture property
4. Test the actual build to ensure no Jekyll errors

🎯 Verdict

Conditional Approval - The PR is well-structured and follows project conventions. The issues identified are minor and should be addressed before merging, but they don't block the overall approach.

Priority Fixes:

1. Add active class to navigation link (consistency)
2. Verify external URLs exist (broken links)

Nice-to-Have:

1. Complete code examples or add clarifying comments
2. Test in local environment per recommendations above

---

Great work on the content quality and bilingual implementation! The technical explanations of Moment, Reason, and Final are clear and philosophically grounded. 🎉

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@_includes/manuals/1.0/header.html`:
- Around line 30-32: The "Demos" nav link missing the conditional active class
should mirror the pattern used for "Home" and "Manual": update the <a
class="nav-link" href="..."> anchor for Demos to conditionally include the
"active" class when the current page is the demos page (use the same page.path
or page.url / page.layout checks used elsewhere), e.g. add the same ternary or
if expression that injects "active" into the class attribute for the anchor
(refer to the existing nav link logic for Home/Manual to copy the exact
condition and class concatenation).

In `@manuals/1.0/en/demos.md`:
- Around line 40-56: The PaymentCompleted readonly class assigns to
$this->capture in the constructor but never declares the property; add a
readonly property declaration (e.g., private readonly <type> $capture) to the
PaymentCompleted class with the correct type returned by
PaymentGatewayInterface::authorize so the constructor can assign it and be() can
call $this->capture->be(); update the property visibility/type to match usage
and the interface return type to keep signatures consistent.

In `@manuals/1.0/ja/demos.md`:
- Around line 40-56: The class PaymentCompleted assigns $this->capture but never
declares it; add a private readonly property declaration for capture in the
PaymentCompleted class (use the concrete type returned by
PaymentGatewayInterface::authorize if known, otherwise use an appropriate union
or mixed) so the readonly class has all properties explicitly declared; keep the
constructor assignment and be() method as-is to initialize and use that declared
property.

[koriym]

@coderabbitai Fixed all 3 issues:

• Added active class condition to Demos nav link
• Added missing capture property declaration in PaymentCompleted (en/ja)

[coderabbitai]

Tip

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the header.html for active class condition on Demos link
echo "=== Checking header.html for active class condition ==="
cat _includes/manuals/1.0/header.html | grep -A 2 -B 2 "Demos"

echo -e "\n=== Checking en/demos.md for capture property ==="
# Look for the PaymentCompleted class and capture property
cat manuals/1.0/en/demos.md | grep -A 20 "class PaymentCompleted"

echo -e "\n=== Checking ja/demos.md for capture property ==="
# Look for the PaymentCompleted class and capture property
cat manuals/1.0/ja/demos.md | grep -A 20 "class PaymentCompleted"

Length of output: 1427

---

@koriym Thank you for addressing all three issues! I've verified the fixes:

✅ Active class condition - The Demos nav link now correctly includes {% if page.url contains 'demos' %}active{% endif %}

✅ PaymentCompleted property (en) - The public PaymentCapture $capture; declaration is now present

✅ PaymentCompleted property (ja) - The public PaymentCapture $capture; declaration is now present

All the code examples are now complete and consistent. Great work! 🎉

---

(ﾉ◕ヮ◕)ﾉ*:･ﾟ✧