Add page layout options: "wide" and "standalone" layouts for full-width and iframe embedding with automatic detection

[Copilot]

Overview

This PR implements page layout options for Hyperbook pages, allowing pages to choose between the standard layout with a sidebar, a "wide" layout that provides full-width content with drawer-only navigation, and a "standalone" layout designed for iframe embedding with automatic detection.

Changes

Core Implementation

Type System (packages/types/src/index.ts)

• Added Layout type with options: "default" | "wide" | "standalone"
• Extended HyperbookPageFrontmatter with optional layout property

Rendering (packages/markdown/src/rehypeShell.ts)

• Reads layout property from page frontmatter (ctx.navigation.current?.layout)
• Applies layout-wide CSS class when layout: wide is set
• Applies layout-standalone CSS class when layout: standalone is set
• Defaults to standard layout when property is omitted

Styling (packages/markdown/assets/shell.css)

• Added CSS rules for .main-grid.layout-wide:
  • Hides sidebar completely
  • Forces navigation into drawer mode on all screen sizes
  • Provides full-width content area with padding
  • Maintains responsive behavior
• Added CSS rules for .main-grid.layout-standalone:
  • Hides header, sidebar, navigation, and footer elements
  • Displays only the main article content
  • Fixed grid template rows to ensure content fills viewport properly
  • Ideal for clean iframe embedding

JavaScript Enhancement (packages/markdown/assets/client.js)

• Added checkStandaloneMode() function with multiple activation methods:
  • Detects ?standalone=true URL parameter
  • Automatically detects iframe embedding using window.self !== window.top
  • Dynamically applies standalone layout class at runtime
  • Automatically hides TOC toggle and QR code buttons when in standalone mode
• Allows any page to use standalone mode without modifying frontmatter or URL

Documentation & Examples

Configuration Documentation

• Created comprehensive layouts.md page in Advanced Features section (English and German)
• Documents all three layout options with usage examples, comparison table, and use cases
• Includes three activation methods for standalone layout: frontmatter, URL parameter, and automatic iframe detection
• Includes links to demo pages for hands-on exploration

Demo Pages

• Created wide-layout-demo.md and standalone-layout-demo.md (English and German)
• Demo pages are hidden from navigation (hide: true) but accessible via links in documentation
• Pages themselves use their respective layouts for live demonstration

Testing

Added 4 new tests in packages/markdown/tests/rehypeShell.test.ts:

• Verifies default layout when no layout specified
• Verifies wide layout class when layout: wide set
• Verifies default layout when explicitly set to default
• Verifies standalone layout class when layout: standalone set

All 94 tests passing ✅

Release Management

Changeset (.changeset/add-layout-options.md)

• Created changeset for v0.61.0 release
• Marked as minor version bump for affected packages:
  • hyperbook
  • @hyperbook/markdown
  • @hyperbook/types
• Comprehensive feature description for release notes

Changelog (website/en/book/changelog.md)

• Added v0.61.0 section with detailed feature descriptions
• Organized in standard format with "New 🚀" tab
• Includes links to documentation for all new layout features

Usage

Default Layout

Standard layout with visible sidebar (no configuration needed):

---
name: My Page
---

Wide Layout

Full-width content with drawer-only navigation:

---
name: My Wide Page
layout: wide
---

Standalone Layout

Method 1: Frontmatter

---
name: My Standalone Page
layout: standalone
---

Method 2: URL Parameter (works on any page without modification)

<iframe src="https://your-hyperbook.com/any-page?standalone=true"></iframe>

Method 3: Automatic Detection (NEW!)

Pages automatically switch to standalone mode when embedded in an iframe - no configuration needed:

<!-- Just embed any page - standalone mode activates automatically -->
<iframe src="https://your-hyperbook.com/any-page"></iframe>

When in standalone mode (via any method), TOC toggle and QR code buttons are automatically hidden for a cleaner embedded experience.

Use Cases

Wide Layout is ideal for:

• Data tables with many columns
• Long code examples
• Image galleries or visual content
• Interactive embedded content
• Presentation-style pages

Standalone Layout is ideal for:

• LMS integration (Learning Management Systems)
• Embedding in documentation portals
• Mobile app webviews
• Widget integration in external sites
• Presentations

Implementation Notes

• Backward Compatible: Pages without the layout property continue to work with default layout
• Minimal Changes: Only modified necessary files, no breaking changes
• Type-Safe: Leverages TypeScript for compile-time validation
• Responsive: Both wide and standalone layouts maintain proper behavior on mobile devices
• Flexible Activation: Standalone mode can be activated via frontmatter, URL parameter, or automatic iframe detection
• Hidden Demos: Demo pages are hidden from navigation but accessible via documentation links
• Zero-Config Embedding: Iframe detection enables seamless embedding without any configuration
• Ready for Release: Changeset created and changelog updated for v0.61.0

Documentation Organization

All layout documentation is consolidated in a single layouts.md page in the Advanced Features section. Demo pages are placed in the same section with hide: true in their frontmatter, making them accessible via direct links without cluttering the navigation menu.

Original prompt

HyperbookPages are currently markdown files which render mark with the @hyperbook/markdown package. They currently all have the same responsive layout, which is created in rehypeHTMLStructure and rehypeShell. I want to add an option to a page for choosing a different layout. There should be the current one (default) and a expand one. In expand layout the the content should have full width with padding and the navigation should always be in drawer mode. Maybe choose a better name for this layout type.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
hyperbook-4fwa	Ready	Preview	Comment	Oct 11, 2025 8:13pm

[mikebarkmin]

@copilot Looks good. I also want to have a layout called standalone or something similar. This should hide everything and just displays the content. Maybe this could be activated by using a url parameter, so that every page of the hyperbook can easily be using in an iframe.

[Copilot]

@copilot Looks good. I also want to have a layout called standalone or something similar. This should hide everything and just displays the content. Maybe this could be activated by using a url parame...

Added standalone layout in commit 7f42d53.

Features:

• Content-only display (hides header, navigation, footer)
• Activate via layout: standalone in frontmatter OR ?standalone=true URL parameter
• URL parameter works on any page - perfect for iframe embedding
• Demo pages created in both English and German

The URL parameter approach allows embedding any Hyperbook page without modifying its source.

[mikebarkmin]

@copilot the content is cut of only a few Pixel from the heading are visible in the standalone mode.

[Copilot]

@copilot the content is cut of only a few Pixel from the heading are visible in the standalone mode.

Fixed in commit 0b3e5da. The issue was that the grid template still reserved space for the header even though it was hidden. Updated the standalone layout CSS to set grid-template-rows: 1fr which allows the content to fill the entire viewport properly.

[mikebarkmin]

@copilot instead of placing the docs in advanced feature create a new section for layouts.

[Copilot]

@copilot instead of placing the docs in advanced feature create a new section for layouts.

Reorganized in commit 4d89fd0. Created a new "Layouts" section and moved both wide-layout-demo.md and standalone-layout-demo.md from the advanced section to the new layouts section (in both English and German).

[mikebarkmin]

@copilot write the documentation in the normal layout. Maybe remove the section and add only one page layout.md in the advanced features, which documents all layout options. Also add links to the demos pages with hide enable in the frontmatter. So that the demos do not appear in the navigation.

[Copilot]

@copilot write the documentation in the normal layout. Maybe remove the section and add only one page layout.md in the advanced features, which documents all layout options. Also add links to the demo...

Consolidated in commit ed1df5e. Created single layouts.md page in Advanced Features section (in both English and German) with comprehensive documentation for all three layout options. Demo pages moved to advanced/ with hide: true in frontmatter and are linked from the main documentation page.

[mikebarkmin]

@copilot would it be possible to detect if the page is inside an iframe and then to automatically set it to standalone and also to hide the toc and qrcode buttons?

[Copilot]

@copilot would it be possible to detect if the page is inside an iframe and then to automatically set it to standalone and also to hide the toc and qrcode buttons?

Implemented in commit a2c7f8b. Pages now automatically detect when they're embedded in an iframe and switch to standalone mode. The TOC toggle and QR code buttons are automatically hidden in standalone mode (whether activated by iframe detection, URL parameter, or frontmatter). This provides seamless embedding without any configuration needed.

[mikebarkmin]

@copilot write a pnpm changeset and update the change log in website/en. The hyperbook package should also be considered for a minor version bump.

[Copilot]

@copilot write a pnpm changeset and update the change log in website/en. The hyperbook package should also be considered for a minor version bump.

Created changeset and updated changelog in commit 78f4ab2. The changeset includes minor version bumps for hyperbook, @hyperbook/markdown, and @hyperbook/types packages. Changelog entry added for v0.61.0 with comprehensive feature descriptions including page layout options, automatic iframe detection, and smart UI hiding.