diff --git a/.changeset/add-layout-options.md b/.changeset/add-layout-options.md new file mode 100644 index 00000000..1b3b86b0 --- /dev/null +++ b/.changeset/add-layout-options.md @@ -0,0 +1,16 @@ +--- +"hyperbook": minor +"@hyperbook/markdown": minor +"@hyperbook/types": minor +--- + +Add page layout options with automatic iframe detection + +- Added three layout options: default, wide, and standalone +- Wide layout provides full-width content with drawer-only navigation, ideal for tables, galleries, and code examples +- Standalone layout displays content only (no header, sidebar, footer) for clean iframe embedding +- Standalone mode can be activated via frontmatter (`layout: standalone`), URL parameter (`?standalone=true`), or automatic iframe detection +- Automatically hides TOC toggle and QR code buttons when in standalone mode +- Zero-configuration embedding: pages automatically switch to standalone mode when embedded in iframes +- Added comprehensive documentation in Advanced Features section with usage examples and demos +- All changes are backward compatible with existing pages diff --git a/packages/markdown/assets/client.js b/packages/markdown/assets/client.js index f916141d..5d51c790 100644 --- a/packages/markdown/assets/client.js +++ b/packages/markdown/assets/client.js @@ -274,9 +274,38 @@ var hyperbook = (function () { initBookmarks(root); } + // Check for standalone layout URL parameter or iframe context + function checkStandaloneMode() { + // Check if explicitly requested via URL parameter + const urlParams = new URLSearchParams(window.location.search); + const standaloneParam = urlParams.get('standalone') === 'true'; + + // Check if page is inside an iframe + const isInIframe = window.self !== window.top; + + if (standaloneParam || isInIframe) { + const mainGrid = document.querySelector('.main-grid'); + if (mainGrid && !mainGrid.classList.contains('layout-standalone')) { + mainGrid.classList.add('layout-standalone'); + } + + // Hide TOC and QR code buttons when in standalone mode + const tocToggle = document.getElementById('toc-toggle'); + if (tocToggle) { + tocToggle.style.display = 'none'; + } + + const qrcodeOpen = document.getElementById('qrcode-open'); + if (qrcodeOpen) { + qrcodeOpen.style.display = 'none'; + } + } + } + // Initialize existing elements on document load document.addEventListener("DOMContentLoaded", () => { init(document); + checkStandaloneMode(); }); // Observe for new elements added to the DOM diff --git a/packages/markdown/assets/shell.css b/packages/markdown/assets/shell.css index c8c545b4..e14995d8 100644 --- a/packages/markdown/assets/shell.css +++ b/packages/markdown/assets/shell.css @@ -807,3 +807,62 @@ nav.toc li.level-3 { flex-shrink: 0; /* Prevent caption from shrinking */ } + +/* Wide layout: full width content with drawer-only navigation */ +.main-grid.layout-wide { + grid-template-columns: 1fr; + grid-template-areas: + "header" + "article"; + + + --main-width: 100%; +} + +.main-grid.layout-wide .sidebar { + display: none; +} + +.main-grid.layout-wide .mobile-nav { + display: flex; + align-items: center; + justify-content: center; +} + +.main-grid.layout-wide main { + padding: 20px 40px; + max-width: 100%; +} + +/* Standalone layout: content only, no navigation or header (for iframe embedding) */ +.main-grid.layout-standalone { + grid-template-columns: 1fr; + grid-template-rows: 1fr; + grid-template-areas: "article"; + + --main-width: 100%; + + #toc-toggle { + top: inherit; + } + + #qrcode-open { + top: 90px; + } +} + +.main-grid.layout-standalone header, +.main-grid.layout-standalone .sidebar { + display: none; +} + +.main-grid.layout-standalone main { + padding: 20px 40px; + max-width: 100%; +} + +.main-grid.layout-standalone .jump-container, +.main-grid.layout-standalone .meta, +.main-grid.layout-standalone #custom-links-footer { + display: none; +} diff --git a/packages/markdown/src/rehypeShell.ts b/packages/markdown/src/rehypeShell.ts index bf08ce7f..ab085b10 100644 --- a/packages/markdown/src/rehypeShell.ts +++ b/packages/markdown/src/rehypeShell.ts @@ -981,12 +981,20 @@ const makeCustomLinksFooter = (ctx: HyperbookContext) => { export default (ctx: HyperbookContext) => () => { return (tree: Root, file: VFile) => { const originalChildren = tree.children as ElementContent[]; + const layout = ctx.navigation.current?.layout || "default"; + let mainGridClass = "main-grid"; + if (layout === "wide") { + mainGridClass = "main-grid layout-wide"; + } else if (layout === "standalone") { + mainGridClass = "main-grid layout-standalone"; + } + tree.children = [ { type: "element", tagName: "div", properties: { - class: "main-grid", + class: mainGridClass, }, children: [ ...makeHeaderElements(ctx), diff --git a/packages/markdown/tests/rehypeShell.test.ts b/packages/markdown/tests/rehypeShell.test.ts index 5c16f449..10036f1f 100644 --- a/packages/markdown/tests/rehypeShell.test.ts +++ b/packages/markdown/tests/rehypeShell.test.ts @@ -47,4 +47,68 @@ describe("rehypeShell", () => { expect(value).toContain("__I_AM_HERE"); expect(value).not.toContain("__I_AM_NOT_HERE"); }); + + it("should apply default layout class when no layout is specified", () => { + const defaultCtx: HyperbookContext = { + ...ctx, + navigation: { + ...ctx.navigation, + current: { + ...ctx.navigation.current!, + layout: undefined, + }, + }, + }; + const value = toHtml("", defaultCtx).value; + expect(value).toContain('class="main-grid"'); + expect(value).not.toContain("layout-wide"); + expect(value).not.toContain("layout-standalone"); + }); + + it("should apply wide layout class when layout is set to wide", () => { + const wideCtx: HyperbookContext = { + ...ctx, + navigation: { + ...ctx.navigation, + current: { + ...ctx.navigation.current!, + layout: "wide", + }, + }, + }; + const value = toHtml("", wideCtx).value; + expect(value).toContain('class="main-grid layout-wide"'); + }); + + it("should apply default layout class when layout is explicitly set to default", () => { + const defaultExplicitCtx: HyperbookContext = { + ...ctx, + navigation: { + ...ctx.navigation, + current: { + ...ctx.navigation.current!, + layout: "default", + }, + }, + }; + const value = toHtml("", defaultExplicitCtx).value; + expect(value).toContain('class="main-grid"'); + expect(value).not.toContain("layout-wide"); + expect(value).not.toContain("layout-standalone"); + }); + + it("should apply standalone layout class when layout is set to standalone", () => { + const standaloneCtx: HyperbookContext = { + ...ctx, + navigation: { + ...ctx.navigation, + current: { + ...ctx.navigation.current!, + layout: "standalone", + }, + }, + }; + const value = toHtml("", standaloneCtx).value; + expect(value).toContain('class="main-grid layout-standalone"'); + }); }); diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts index 274dba78..93395f64 100644 --- a/packages/types/src/index.ts +++ b/packages/types/src/index.ts @@ -34,6 +34,8 @@ export type Glossary = Record; export type Language = "de" | "en" | "fr" | "es" | "it" | "pt" | "nl"; +export type Layout = "default" | "wide" | "standalone"; + export type HyperbookPageFrontmatter = { name: string; permaid?: string; @@ -48,6 +50,7 @@ export type HyperbookPageFrontmatter = { toc?: boolean; next?: string; prev?: string; + layout?: Layout; }; export type HyperbookSectionFrontmatter = HyperbookPageFrontmatter & { diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 1a3241f1..15bf1909 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,7 +1,8 @@ packages: - # all packages in subdirs of packages/ and components/ - - "packages/*" - - "templates/*" - - "platforms/*" - # exclude packages that are inside test directories - - "!**/test/**" + - packages/* + - templates/* + - platforms/* + - '!**/test/**' + +onlyBuiltDependencies: + - sharp diff --git a/website/de/book/advanced/layouts.md b/website/de/book/advanced/layouts.md new file mode 100644 index 00000000..eb64b8af --- /dev/null +++ b/website/de/book/advanced/layouts.md @@ -0,0 +1,142 @@ +--- +name: Layouts +index: 8 +lang: de +--- + +# Seiten-Layouts + +Hyperbook bietet drei Layout-Optionen für unterschiedliche Anforderungen an die Inhaltsdarstellung. Sie können ein Layout wählen, indem Sie die `layout` Eigenschaft im Frontmatter Ihrer Seite hinzufügen. + +## Verfügbare Layouts + +### Standard-Layout + +Das Standardlayout mit sichtbarer Seitenleiste auf Desktop-Bildschirmen. Dies ist das Standardlayout, wenn kein Layout angegeben wird. + +**Merkmale:** +- Seitenleisten-Navigation auf Desktop immer sichtbar +- Inhaltsbereich mit optimaler Lesebreite +- Responsives Design, das auf Mobilgeräten zur Drawer-Navigation wechselt + +**Verwendung:** +```md +--- +name: Meine Seite +layout: default +--- +``` + +Oder lassen Sie die `layout` Eigenschaft einfach weg. + +**Am besten für:** Standard-Dokumentationsseiten, Tutorials und Artikel. + +--- + +### Wide Layout + +Inhalt in voller Breite mit Navigation immer im Drawer-Modus, bietet maximalen horizontalen Platz. + +**Merkmale:** +- Inhalt erstreckt sich über volle Breite mit Padding +- Seitenleiste auf allen Bildschirmgrößen versteckt +- Navigation über Hamburger-Menü zugänglich +- Ideal für Inhalte, die horizontalen Platz benötigen + +**Verwendung:** +```md +--- +name: Meine Breite Seite +layout: wide +--- +``` + +**Am besten für:** +- Datentabellen mit vielen Spalten +- Lange Code-Beispiele +- Bildergalerien +- Interaktive eingebettete Inhalte +- Präsentations-Seiten + +**[Wide Layout Demo ansehen →](/de/advanced/wide-layout-demo)** + +--- + +### Standalone Layout + +Nur-Inhalts-Anzeige mit allen versteckten Navigations- und UI-Elementen, perfekt für iframe-Einbettung. + +**Merkmale:** +- Keine Header-, Seitenleisten- oder Footer-Elemente +- Saubere, ablenkungsfreie Inhalte +- Kann über Frontmatter, URL-Parameter oder automatisch in iframes aktiviert werden +- Entwickelt für die Einbettung in externe Seiten +- Versteckt automatisch TOC- und QR-Code-Buttons + +**Verwendungsmethode 1: Frontmatter** +```md +--- +name: Meine Standalone-Seite +layout: standalone +--- +``` + +**Verwendungsmethode 2: URL-Parameter** (funktioniert auf jeder Seite) +```html + +``` + +**Verwendungsmethode 3: Automatische Erkennung** (iframe-Einbettung) + +Wenn eine Hyperbook-Seite in einem iframe eingebettet wird, wechselt sie automatisch in den Standalone-Modus - keine Konfiguration erforderlich! Dies ermöglicht eine nahtlose Einbettung ohne URL-Parameter oder Frontmatter-Änderungen. + +```html + + +``` + +Die automatische Erkennung sorgt für saubere, ablenkungsfreie Inhalte bei iframe-Einbettungen und behält gleichzeitig die volle Funktionalität bei, wenn Seiten direkt aufgerufen werden. + +**Am besten für:** +- Lernmanagementsystem (LMS) Integration +- Einbettung in Dokumentationsportale +- Mobile App Webviews +- Widget-Integration +- Präsentationen + +**[Standalone Layout Demo ansehen →](/de/advanced/standalone-layout-demo)** + +--- + +## Konfiguration + +Die Layout-Eigenschaft ist optional im Frontmatter Ihrer Seite: + +```md +--- +name: Seitentitel +layout: wide # oder 'default', 'standalone' +--- + +# Ihr Inhalt hier +``` + +## Layout-Vergleich + +| Merkmal | Standard | Wide | Standalone | +|---------|---------|------|------------| +| Seitenleisten-Sichtbarkeit | Sichtbar auf Desktop | Immer versteckt | Immer versteckt | +| Inhaltsbreite | Begrenzt für Lesbarkeit | Volle Breite | Volle Breite | +| Navigationszugriff | Seitenleiste / Drawer | Nur Drawer | Keine (versteckt) | +| Header | Sichtbar | Sichtbar | Versteckt | +| Footer | Sichtbar | Sichtbar | Versteckt | +| Bester Anwendungsfall | Dokumentation | Tabellen, Galerien | iframe-Einbettung | + +--- + +## Tipps + +- **Standard-Layout**: Verwenden Sie es für die meisten Dokumentationsseiten, um eine konsistente Navigation zu gewährleisten +- **Wide Layout**: Wechseln Sie zu wide, wenn Inhalte horizontalen Platz benötigen (Tabellen, Code, Galerien) +- **Standalone Layout**: Verwenden Sie den URL-Parameter (`?standalone=true`) für flexible iframe-Einbettung ohne Änderung der Seitenquelle +- Sie können verschiedene Layouts über Seiten im selben Hyperbook-Projekt mischen diff --git a/website/de/book/advanced/standalone-layout-demo.md b/website/de/book/advanced/standalone-layout-demo.md new file mode 100644 index 00000000..2a68d187 --- /dev/null +++ b/website/de/book/advanced/standalone-layout-demo.md @@ -0,0 +1,84 @@ +--- +name: Standalone Layout Demo +layout: standalone +hide: true +lang: de +--- + +# Standalone Layout Demo + +Diese Seite demonstriert das **Standalone Layout** Feature, welches nur den Inhalt ohne Navigation, Header oder Footer-Elemente anzeigt. + +## Zweck + +Das Standalone Layout ist speziell für die **iframe-Einbettung** konzipiert und ermöglicht die nahtlose Integration von Hyperbook-Seiten in andere Websites oder Anwendungen. + +## Hauptmerkmale + +- **Nur Inhalt**: Keine Header, Seitenleiste, Navigation oder Footer-Elemente +- **Klare Darstellung**: Perfekt für die Einbettung in externe Seiten +- **Voller Fokus**: Leser sehen nur den Inhalt ohne Ablenkungen +- **Einfache Integration**: Funktioniert nahtlos in iframes + +## Verwendung + +### Methode 1: Seiten-Frontmatter + +Setzen Sie das Layout im Frontmatter Ihrer Seite: + +```md +--- +name: Meine Standalone-Seite +layout: standalone +--- + +# Ihr Inhalt hier +``` + +### Methode 2: URL-Parameter (Empfohlen für iframes) + +Fügen Sie `?standalone=true` zu jeder Seiten-URL hinzu: + +```html + +``` + +Diese Methode ermöglicht es, **jede Seite** im Standalone-Modus anzuzeigen, ohne deren Frontmatter zu ändern. + +## Beispielverwendung + +```html + + +``` + +## Anwendungsfälle + +- **Lernmanagementsysteme**: Lektionen direkt in LMS-Plattformen einbetten +- **Dokumentationsportale**: Spezifische Seiten in größere Dokumentationsseiten einbinden +- **Präsentationen**: Inhalt in Präsentationstools anzeigen +- **Mobile Apps**: Webinhalte in eingebetteten Webviews zeigen +- **Widget-Integration**: Hyperbook-Inhalte als Widgets einbinden + +## Was ist im Standalone-Modus versteckt? + +Wenn das Standalone Layout aktiv ist, werden folgende Elemente ausgeblendet: + +- Header mit Logo und Navigation +- Seitenleisten-Navigation +- Vorherige/Nächste-Seite-Buttons +- Footer-Metadaten und Links +- Suchfunktion +- Dark Mode Toggle + +Nur der Hauptartikel-Inhalt bleibt sichtbar. + +## Test + +Betrachten Sie diese Seite mit dem URL-Parameter, um den Standalone-Modus zu sehen: +[Diese Seite mit ?standalone=true](/de/advanced/standalone-layout-demo?standalone=true) diff --git a/website/de/book/advanced/wide-layout-demo.md b/website/de/book/advanced/wide-layout-demo.md new file mode 100644 index 00000000..bb590bfc --- /dev/null +++ b/website/de/book/advanced/wide-layout-demo.md @@ -0,0 +1,75 @@ +--- +name: Wide Layout Demo +layout: wide +hide: true +lang: de +--- + +# Wide Layout Demo + +Diese Seite demonstriert das **Wide Layout** Feature, welches vollbreiten Inhalt mit Navigation im Drawer-Modus bietet. + +## Hauptmerkmale des Wide Layouts + +Das Wide Layout ist ideal für Seiten, die maximalen horizontalen Platz benötigen: + +- **Vollbreiter Inhalt**: Der Inhalt erstreckt sich über die gesamte Seitenbreite mit Padding +- **Nur Drawer-Navigation**: Die Seitenleiste ist immer versteckt, Navigation erfolgt über das Hamburger-Menü +- **Responsives Design**: Funktioniert nahtlos auf allen Bildschirmgrößen +- **Einfache Konfiguration**: Einfach `layout: wide` zum Seiten-Frontmatter hinzufügen + +## Verwendung + +Um das Wide Layout zu verwenden, fügen Sie einfach die `layout` Eigenschaft zum Frontmatter Ihrer Seite hinzu: + +```md +--- +name: Meine Breite Seite +layout: wide +--- + +# Ihr Inhalt hier +``` + +## Wann Wide Layout verwenden + +Erwägen Sie das Wide Layout für: + +- **Datentabellen**: Seiten mit breiten Tabellen, die horizontalen Platz benötigen +- **Code-Beispiele**: Seiten mit langen Code-Snippets, die von breiterer Anzeige profitieren +- **Galerien**: Bildergalerien oder visueller Inhalt, der volle Breite benötigt +- **Interaktiver Inhalt**: Seiten mit eingebetteten interaktiven Elementen, die Platz benötigen +- **Präsentationen**: Inhalte, die in einem präsentationsähnlichen Format besser funktionieren + +## Beispiel: Breite Tabelle + +Hier ist eine Tabelle, die vom zusätzlichen horizontalen Platz des Wide Layouts profitiert: + +| Merkmal | Standard Layout | Wide Layout | Beschreibung | +|---------|----------------|-------------|--------------| +| Inhaltsbreite | Begrenzt durch Seitenleiste | Volle Breite mit Padding | Wide Layout bietet mehr horizontalen Platz | +| Navigation | Seitenleiste auf Desktop immer sichtbar | Immer im Drawer-Modus | Maximiert Inhaltsbereich | +| Am besten für | Standard-Dokumentation | Tabellen, Galerien, Präsentationen | Wählen Sie basierend auf Inhaltsbedürfnissen | +| Mobile Verhalten | Verwendet Drawer-Navigation | Verwendet Drawer-Navigation | Konsistente mobile Erfahrung | +| Konfiguration | `layout: default` oder weglassen | `layout: wide` | Einfache Frontmatter-Option | + +## Beispiel: Code-Block + +```javascript +// Wide Layout bietet mehr horizontalen Platz für Code +function demonstriereWideLayout() { + const merkmale = ['vollbreiter-inhalt', 'drawer-navigation', 'responsives-design']; + return merkmale.map(merkmal => { + console.log(`Wide Layout Merkmal: ${merkmal} - jetzt können Sie längere Zeilen ohne Scrollen sehen!`); + return merkmal; + }); +} +``` + +## Vergleich + +Wechseln Sie zwischen dieser Seite und anderen Dokumentationsseiten, um den Unterschied zwischen Standard- und Wide Layout zu sehen. Beachten Sie, wie sich der Inhaltsbereich auf dieser Seite über die volle Breite Ihres Browserfensters erstreckt, während Standardseiten eine Seitenleiste auf Desktop-Bildschirmen beibehalten. + +--- + +**Hinweis**: Sie können jederzeit zum Standard-Layout zurückkehren, indem Sie die `layout` Eigenschaft entfernen oder auf `default` setzen. diff --git a/website/de/book/configuration/page.md b/website/de/book/configuration/page.md index d40f43b2..1f068405 100644 --- a/website/de/book/configuration/page.md +++ b/website/de/book/configuration/page.md @@ -42,6 +42,7 @@ Hier sind die Eigenschaften, die im Frontmatter gesetzt werden können: | next | Ein absoluter Pfad zur nächsten Seite or ein absoluter Pfad zur permaid z. B. /@/audio. Dies überschreibt index und hide. Du kannst außerdem nichts setzen, sodass der Button versteckt wird. | | hide | Verstecke die Seite von der Navigation. | | toc | Zeige ein Inhaltsverzeichnis. Diese ist standardmäßig aktiviert für Seiten und deaktiviert für Begriffe im Glossar. | +| layout | Wähle das Seitenlayout. Optionen: `default` (Standardlayout mit Seitenleiste), `wide` (Inhalt in voller Breite mit Navigation im Drawer-Modus) oder `standalone` (nur Inhalt, versteckt alle Navigation - ideal für iframe-Einbettung). Das standalone Layout kann auch über URL-Parameter aktiviert werden: `?standalone=true` | | qrcode | Zeigt ein Icon, um einen QR-Code zur Seite anzuzeigen | | styles | Hier können Links zu eigenen CSS-Styles gesetzt werden. | | scripts | Hier können Links zu eigenen JavaScript-Dateien gesetzt werden. | diff --git a/website/en/book/advanced/layouts.md b/website/en/book/advanced/layouts.md new file mode 100644 index 00000000..62b9c988 --- /dev/null +++ b/website/en/book/advanced/layouts.md @@ -0,0 +1,141 @@ +--- +name: Layouts +index: 8 +--- + +# Page Layouts + +Hyperbook provides three layout options to suit different content presentation needs. You can choose a layout by adding the `layout` property to your page's frontmatter. + +## Available Layouts + +### Default Layout + +The standard layout with a visible sidebar on desktop screens. This is the default if no layout is specified. + +**Features:** +- Sidebar navigation always visible on desktop +- Content area with optimal reading width +- Responsive design that switches to drawer navigation on mobile + +**Usage:** +```md +--- +name: My Page +layout: default +--- +``` + +Or simply omit the `layout` property entirely. + +**Best for:** Standard documentation pages, tutorials, and articles. + +--- + +### Wide Layout + +Full-width content with navigation always in drawer mode, providing maximum horizontal space. + +**Features:** +- Content spans full width with padding +- Sidebar hidden on all screen sizes +- Navigation accessed via hamburger menu +- Ideal for content requiring horizontal space + +**Usage:** +```md +--- +name: My Wide Page +layout: wide +--- +``` + +**Best for:** +- Data tables with many columns +- Long code examples +- Image galleries +- Interactive embedded content +- Presentation-style pages + +**[View Wide Layout Demo →](/advanced/wide-layout-demo)** + +--- + +### Standalone Layout + +Content-only display with all navigation and UI elements hidden, perfect for iframe embedding. + +**Features:** +- No header, sidebar, or footer elements +- Clean, distraction-free content +- Can be activated via frontmatter, URL parameter, or automatically when in iframe +- Designed for embedding in external sites +- Automatically hides TOC and QR code buttons + +**Usage Method 1: Frontmatter** +```md +--- +name: My Standalone Page +layout: standalone +--- +``` + +**Usage Method 2: URL Parameter** (works on any page) +```html + +``` + +**Usage Method 3: Automatic Detection** (iframe embedding) + +When a Hyperbook page is embedded in an iframe, it automatically switches to standalone mode - no configuration needed! This provides seamless embedding without requiring URL parameters or frontmatter changes. + +```html + + +``` + +The automatic detection ensures clean, distraction-free content for iframe embeds while maintaining full functionality when pages are accessed directly. + +**Best for:** +- Learning Management System (LMS) integration +- Embedding in documentation portals +- Mobile app webviews +- Widget integration +- Presentations + +**[View Standalone Layout Demo →](/advanced/standalone-layout-demo)** + +--- + +## Configuration + +The layout property is optional in your page frontmatter: + +```md +--- +name: Page Title +layout: wide # or 'default', 'standalone' +--- + +# Your Content Here +``` + +## Layout Comparison + +| Feature | Default | Wide | Standalone | +|---------|---------|------|------------| +| Sidebar Visibility | Visible on desktop | Always hidden | Always hidden | +| Content Width | Limited for readability | Full width | Full width | +| Navigation Access | Sidebar / Drawer | Drawer only | None (hidden) | +| Header | Visible | Visible | Hidden | +| Footer | Visible | Visible | Hidden | +| Best Use Case | Documentation | Tables, galleries | Iframe embedding | + +--- + +## Tips + +- **Default Layout**: Use for most documentation pages to maintain consistent navigation +- **Wide Layout**: Switch to wide when content needs horizontal space (tables, code, galleries) +- **Standalone Layout**: Use the URL parameter (`?standalone=true`) for flexible iframe embedding without modifying page source +- You can mix different layouts across pages in the same Hyperbook project diff --git a/website/en/book/advanced/standalone-layout-demo.md b/website/en/book/advanced/standalone-layout-demo.md new file mode 100644 index 00000000..0cf0887f --- /dev/null +++ b/website/en/book/advanced/standalone-layout-demo.md @@ -0,0 +1,83 @@ +--- +name: Standalone Layout Demo +layout: standalone +hide: true +--- + +# Standalone Layout Demo + +This page demonstrates the **standalone layout** feature, which displays only the content without any navigation, header, or footer elements. + +## Purpose + +The standalone layout is designed specifically for **iframe embedding**, allowing Hyperbook pages to be seamlessly integrated into other websites or applications. + +## Key Features + +- **Content Only**: No header, sidebar, navigation, or footer elements +- **Clean Presentation**: Perfect for embedding in external sites +- **Full Focus**: Readers see only the content without distractions +- **Easy Integration**: Works seamlessly in iframes + +## How to Use + +### Method 1: Page Frontmatter + +Set the layout in your page's frontmatter: + +```md +--- +name: My Standalone Page +layout: standalone +--- + +# Your Content Here +``` + +### Method 2: URL Parameter (Recommended for iframes) + +Add `?standalone=true` to any page URL: + +```html + +``` + +This method allows **any page** to be displayed in standalone mode without modifying its frontmatter. + +## Example Usage + +```html + + +``` + +## Use Cases + +- **Course Management Systems**: Embed lessons directly in LMS platforms +- **Documentation Portals**: Include specific pages in larger documentation sites +- **Presentations**: Display content in presentation tools +- **Mobile Apps**: Show web content in embedded webviews +- **Widget Integration**: Include Hyperbook content as widgets + +## What's Hidden in Standalone Mode? + +When standalone layout is active, the following elements are hidden: + +- Header with logo and navigation +- Sidebar navigation +- Previous/Next page buttons +- Footer metadata and links +- Search functionality +- Dark mode toggle + +Only the main article content remains visible. + +## Testing + +View this page with the URL parameter to see standalone mode: +[This page with ?standalone=true](/advanced/standalone-layout-demo?standalone=true) diff --git a/website/en/book/advanced/wide-layout-demo.md b/website/en/book/advanced/wide-layout-demo.md new file mode 100644 index 00000000..0adddbcc --- /dev/null +++ b/website/en/book/advanced/wide-layout-demo.md @@ -0,0 +1,74 @@ +--- +name: Wide Layout Demo +layout: wide +hide: true +--- + +# Wide Layout Demo + +This page demonstrates the **wide layout** feature, which provides full-width content with navigation always available in drawer mode. + +## Key Features of Wide Layout + +The wide layout is ideal for pages that need maximum horizontal space: + +- **Full-Width Content**: Content spans the entire page width with padding +- **Drawer-Only Navigation**: The sidebar is always hidden, and navigation is accessed via the hamburger menu +- **Responsive Design**: Works seamlessly on all screen sizes +- **Simple Configuration**: Just add `layout: wide` to your page frontmatter + +## Usage + +To use the wide layout, simply add the `layout` property to your page frontmatter: + +```md +--- +name: My Wide Page +layout: wide +--- + +# Your Content Here +``` + +## When to Use Wide Layout + +Consider using the wide layout for: + +- **Data Tables**: Pages with wide tables that need horizontal space +- **Code Examples**: Pages with long code snippets that benefit from wider display +- **Galleries**: Image galleries or visual content that needs full width +- **Interactive Content**: Pages with embedded interactive elements that need space +- **Presentations**: Content that works better in a presentation-like format + +## Example: Wide Table + +Here's a table that benefits from the wide layout's extra horizontal space: + +| Feature | Default Layout | Wide Layout | Description | +|---------|---------------|-------------|-------------| +| Content Width | Limited by sidebar | Full width with padding | Wide layout provides more horizontal space | +| Navigation | Sidebar always visible on desktop | Always in drawer mode | Maximizes content area | +| Best For | Standard documentation | Tables, galleries, presentations | Choose based on content needs | +| Mobile Behavior | Uses drawer navigation | Uses drawer navigation | Consistent mobile experience | +| Configuration | `layout: default` or omit | `layout: wide` | Simple frontmatter option | + +## Example: Code Block + +```javascript +// Wide layout provides more horizontal space for code +function demonstrateWideLayout() { + const features = ['full-width-content', 'drawer-navigation', 'responsive-design']; + return features.map(feature => { + console.log(`Wide layout feature: ${feature} - now you can see longer lines without scrolling!`); + return feature; + }); +} +``` + +## Comparison + +Switch between this page and other documentation pages to see the difference between default and wide layouts. Notice how the content area on this page extends to the full width of your browser window, while standard pages maintain a sidebar on desktop screens. + +--- + +**Note**: You can switch back to the default layout at any time by removing the `layout` property or setting it to `default`. diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md index dcb2785b..918f13c0 100644 --- a/website/en/book/changelog.md +++ b/website/en/book/changelog.md @@ -38,6 +38,25 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo :::: --> +## v0.61.0 + +::::tabs + +:::tab{title="New :rocket:" id="new"} + +- **Page Layout Options**: Added three layout options for Hyperbook pages: + - **Default Layout**: Standard layout with visible sidebar (unchanged behavior for existing pages) + - **Wide Layout**: Full-width content with drawer-only navigation, ideal for data tables, code examples, and galleries. [Learn more](/advanced/layouts) + - **Standalone Layout**: Content-only display (no header, sidebar, footer) perfect for iframe embedding. [Learn more](/advanced/layouts) +- **Automatic Iframe Detection**: Pages automatically switch to standalone mode when embedded in iframes - zero configuration needed! +- **Three Activation Methods for Standalone**: Can be activated via frontmatter (`layout: standalone`), URL parameter (`?standalone=true`), or automatic iframe detection +- **Smart UI Hiding**: TOC toggle and QR code buttons automatically hide in standalone mode for cleaner embedded experience +- **Backward Compatible**: All existing pages work unchanged without any configuration + +::: + +:::: + ## v0.60.0 ::::tabs diff --git a/website/en/book/configuration/page.md b/website/en/book/configuration/page.md index df783c35..20253071 100644 --- a/website/en/book/configuration/page.md +++ b/website/en/book/configuration/page.md @@ -33,6 +33,7 @@ Here are the properties you can set in the frontmatter: | next | The absoulte path to the next page or a absolute path to a permaid e.g. /@/audio. This overrides index and hide. You can also set it to nothing and it will hide the next button. | | hide | Hides the page from the navigation | | toc | Show or hide a table of content for the page. This is on for pages and off for glossary entries by default | +| layout | Choose the page layout. Options: `default` (standard layout with sidebar), `wide` (full-width content with navigation in drawer mode), or `standalone` (content only, hides all navigation - ideal for iframe embedding). The standalone layout can also be activated via URL parameter: `?standalone=true` | | styles | Here you can add Links to custom CSS files. | | scripts | Here you can add links to custom JavaScript files. | | qrcode | Shows an icon, which opens a qr code to this page. |