From f701a99d31a866fe623c1cc41161cd4842a94ca6 Mon Sep 17 00:00:00 2001 From: erkamyaman Date: Sun, 1 Nov 2026 15:38:41 +0300 Subject: [PATCH 1/3] docs: add a page for the deck browser --- src/content/built-in/headmatter.md | 1 + src/content/features/deck-browser.md | 86 ++++++++++++++++++++++++++++ src/content/migrating/from-slidev.md | 2 + src/content/project/security.md | 2 + 4 files changed, 91 insertions(+) create mode 100644 src/content/features/deck-browser.md diff --git a/src/content/built-in/headmatter.md b/src/content/built-in/headmatter.md index d92db19..d167960 100644 --- a/src/content/built-in/headmatter.md +++ b/src/content/built-in/headmatter.md @@ -45,6 +45,7 @@ The first block of YAML in `slides.md` is the headmatter. It describes the deck. | `routerMode` | `history` (default), `hash` or `memory`. See [Slide addresses](../features/routing.md). | | `clickAnimation` | The click animation preset of every slide. | | `navPosition` | Where the navigation bar sits on the slide page: `bottom-left` (default), `bottom-center`, `bottom-right`, `top-left`, `top-center` or `top-right`. Left and right follow the writing direction, so a right-to-left deck mirrors them. At the top, the bar's menus open below it. A viewer can choose another place in the [settings menu](./shortcuts.md#mouse). The presenter page keeps its bar. Another value is warned about and keeps the bottom left. Not in Slidev. | +| `browser` | The [deck browser](../features/deck-browser.md). `false` removes it. `{ links: false }` keeps links on slides opening a new browser tab. `tabs` lists pages for the start page (`[{ name: Docs, url: https://angular.dev }]` or plain addresses), and `search` is the search address with `%s` for the words (DuckDuckGo by default). The generator warns about other values. Not in Slidev. | | `progressBar` | A progress bar on every slide: `true`, `top`, `bottom` or an object. See [Progress bar](../features/progress-bar.md). | | `preloadImages` | `true` (default), `{ ahead: n }` or `false`. See [Loading pictures ahead](../features/preload-images.md). | | `unocss` | `{ attributify: false }` turns attributify off. See [UnoCSS](../features/unocss.md). | diff --git a/src/content/features/deck-browser.md b/src/content/features/deck-browser.md new file mode 100644 index 0000000..69cdd9c --- /dev/null +++ b/src/content/features/deck-browser.md @@ -0,0 +1,86 @@ +--- +title: Deck browser +description: A browser inside the deck, so a talk can show websites without leaving the slides. +--- + +# Deck browser + +slide.ng's own, new in 3.0. Press `b`, or the globe button in the bar, and a browser opens as a layer over the current slide. The **Slides** button, `b` or Escape close it and bring back the same slide and click. Its tabs stay loaded while it is closed, so a page you prepared is still there when you come back to it. + +## Links on slides + +A click on a link to another site, on a slide, opens it in a tab of the deck browser, or in the tab that already shows it. Cmd, Ctrl, Shift or Alt with the click, or a middle click, opens the browser's own tab as before. Links inside the deck move through the slides as always. + +```md +--- +browser: + links: false # links on slides open a new browser tab, as in 2.x +--- +``` + +## What it has + +- **Tabs** with the site's icon. They can be closed and dragged into another order. +- **Back, forward, home and reload.** Back and forward move through the pages a tab showed. +- **An address field** that takes an address (`angular.dev`, `localhost:4200/demo`) or words to search for. A single word searches. +- **Bookmarks.** The star in the address field bookmarks the page. Bookmarks show in a bar under the toolbar, in the bookmarks menu and first on the start page. +- **Open in window** opens the real page in a window over the deck browser, for a site that only works there (some sign-ins, for example). +- **The start page**, which a new tab opens on: a search box, and tiles for the bookmarks, the deck's `browser.tabs` and the pages opened recently. A tile can be removed. +- **The gear menu**: the search engine, whether slide links open in the deck browser, whether the bookmarks bar shows, and buttons that clear the recent pages and the bookmarks. + +## Customise + +**Customise**, on the start page or in the gear menu, opens a larger window: + +- **Background** of the start page: the slide.ng artwork (default), solid colours, gradients or images uploaded from this device. Each kind can pick a new one on every new tab. Text stays readable on light and dark backgrounds. +- **Appearance**: like the deck, light or dark. +- **Search engine**: DuckDuckGo (default), Bing, Wikipedia, or your own address with `%s` for the words. +- **Shortcuts**: which groups of tiles show. +- **Clock and date**: the time and the date, with or without seconds, 12 or 24 hours, a font, a size and a date style. +- **Weather**, off until you turn it on. Turning it on asks for your location; you can also type a city. It shows the current condition, high and low, feels-like, wind and humidity, with a five-day forecast on hover, in °C or °F. +- **Links and data**: the same switches as the gear menu. + +Everything is kept in this browser for this deck, and wins over the headmatter. + +## In the headmatter + +```md +--- +browser: + tabs: + - name: Docs + url: https://angular.dev + search: https://www.bing.com/search?q=%s +--- +``` + +| Key | What it does | +| --- | --- | +| `browser: false` | Removes the deck browser: the key, the button and the link handling. | +| `links` | `false` keeps links on slides opening a new browser tab. | +| `tabs` | Pages that show as shortcut tiles on the start page. A plain address works too. | +| `search` | The search address, with `%s` for the words. DuckDuckGo by default. | + +The generator warns about other values. + +## With the dev server: the proxy + +Many sites refuse to be shown inside another page. With `slide-ng dev` on your machine, pages load through a proxy in the dev server's companion, so these sites (GitHub, most large sites) still show inside the deck, and the address field follows the clicks inside a page. + +- Each site gets its own address under `localhost`, with a random key for each session, apart from the deck and from the other sites. +- The proxy drops the headers that refuse framing, keeps each site's cookies on its own address, turns off service workers and sends links that open a new window to a new tab. +- An address on your computer or your local network, such as `localhost:4200` or a router, loads only when you opened it: from the address field, a slide link, a tile or a bookmark. A page in the deck browser cannot open one. +- Some sites still break through it, for example sign-ins that check where they run. **Open in window** shows the real page. +- Google and some other search engines show a bot check through the proxy, so DuckDuckGo is the default. + +Without the proxy (a built deck, or `--remote`), pages load directly. With the dev server running, a site that refuses framing gets a card with **Open in window**. In a built deck such a site stays blank and the same button is in the toolbar. Back, forward and the address field then only know the pages opened from the deck, not the clicks inside a page. + +See [Security](../project/security.md#what-the-tool-checks) for what the proxy checks. + +## Fullscreen + +In fullscreen, Escape first closes the deck browser and keeps fullscreen, and the next Escape leaves fullscreen. For that the deck takes the Escape key when it goes fullscreen, which Chrome and Edge allow (they show "Press and hold Esc to exit full screen"). In Brave, Firefox and Safari, Escape leaves fullscreen at once. + +## Several windows + +The page shown in the deck browser is part of what the windows share, so the other windows follow it. The presenter page shows which page is open, with a button that closes it everywhere. diff --git a/src/content/migrating/from-slidev.md b/src/content/migrating/from-slidev.md index b12e7b3..3aece25 100644 --- a/src/content/migrating/from-slidev.md +++ b/src/content/migrating/from-slidev.md @@ -22,6 +22,8 @@ slide.ng reads the same markdown file format as *Slidev, with the same slide spl - A progress bar on the slides, `progressBar` or ``. Slidev has one on its presenter page only. See [Progress bar](../features/progress-bar.md). - `navPosition` puts the navigation bar in any corner, or in the middle of the top or bottom edge. A viewer can also move it from the settings menu. Slidev's bar is always at the bottom left. See [Headmatter and frontmatter](../built-in/headmatter.md#the-deck-and-its-look). - `slide-ng.config.yaml` next to `slides.md` holds the deck's options with the keys of the headmatter, and the headmatter wins key by key. See [The config file](../built-in/headmatter.md#the-config-file-slide-ng-config-yaml). +- A [deck browser](../features/deck-browser.md): `b` opens a browser with tabs over the slides, links on slides open in it, and with the dev server a proxy shows sites that refuse framing. +- The navigation bar can be dragged by its grip to another place. - A built-in Turkish interface and `locales/.json` to translate the interface. See [Interface language](../features/interface-language.md). - One deck in several languages, with a language menu in the bar that switches the slides and the interface. See [Interface language](../features/interface-language.md#one-deck-in-several-languages). diff --git a/src/content/project/security.md b/src/content/project/security.md index ad2f811..d78e1a1 100644 --- a/src/content/project/security.md +++ b/src/content/project/security.md @@ -25,6 +25,8 @@ A deck can contain Angular templates, components, setup files and themes, and sl **The MCP server.** Every change is parsed again before it is written, and only the deck's own markdown files are touched. The dev server's MCP endpoint, `/__mcp`, has the dev server's Host and Origin checks, and with `--remote` it needs the password as a bearer token; wrong ones are limited like the login. `mcp: false` in the headmatter turns it off. +**The deck browser.** With `slide-ng dev` on your machine, the [deck browser](../features/deck-browser.md) loads pages through a proxy in the companion server, on `127.0.0.1` and a port of its own (not with `--remote`). It answers only addresses of the form `...localhost` with a random key for each session, so each site has its own origin, apart from the deck and from the other sites: a page shown in it cannot read the deck's storage, and the dev server refuses its requests. The proxy refuses the deck's own servers. An address on your computer or a private network loads only after the deck asked for it, because you typed it or clicked a slide link, tile or bookmark, never because a page pointed at it. The address is checked again on every connection, so a name that changes its answer is refused too. It drops the headers that refuse framing and the site's Content-Security-Policy, so a page in it has less protection against clickjacking than in a tab: it is meant for showing pages during a talk. The weather on its start page is off until you turn it on; it then asks Open-Meteo for the place, and "use my location" asks OpenStreetMap's Nominatim for the city name. + **The code runner.** `{monaco-run}` code runs in a sandboxed frame with no access to the slides, and stops after 5 seconds. ## Options that make the build machine fetch things From 8dad965121d51684a22f257046a1cc327afced59 Mon Sep 17 00:00:00 2001 From: erkamyaman Date: Sun, 1 Nov 2026 15:38:41 +0300 Subject: [PATCH 2/3] docs: drag the navigation bar and open the deck browser with b --- src/content/built-in/shortcuts.md | 5 ++++- src/content/features/context-menu.md | 2 ++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/built-in/shortcuts.md b/src/content/built-in/shortcuts.md index 693c00c..89122b3 100644 --- a/src/content/built-in/shortcuts.md +++ b/src/content/built-in/shortcuts.md @@ -17,12 +17,13 @@ description: The keyboard and mouse controls of a deck, and how to change them. | `g` | Go to a slide: type a number or part of a title, in any case and with or without accents, then Enter | | Escape | Close the overview, dialogs and menus | | `u` | Presenter page: show or hide the [click preview](../guide/presenter-mode.md#click-preview) | +| `b` | Slide page: open or close the [deck browser](../features/deck-browser.md). Escape closes it too. In fullscreen the first Escape closes it and the next one leaves fullscreen (Chrome and Edge) | Shortcuts are off while you type in a text field or an editor, and while the drawing toolbar is open. Escape leaves a text field (not an editor), so the keys work again. After a click on a checkbox or a button, the arrow keys still move the slides. While the info dialog or a modal `` of a slide is open, only Escape works. When a `slide-ng-drag` element is selected, the arrow keys nudge it instead of moving through the slides. ## Mouse -The bar at the bottom left has buttons for fullscreen, previous, next, overview, dark mode, drawing, presenter mode, info, sync mode, settings and a counter. A deck with `languages` also has a language button before the settings, see [One deck in several languages](../features/interface-language.md#one-deck-in-several-languages). The bar shows when the mouse is there. `navPosition` in the headmatter puts it in another corner, or in the middle of the top or bottom edge, see [Headmatter and frontmatter](./headmatter.md#the-deck-and-its-look), and a viewer can move it from the settings menu. On the presenter page the bar stays where it is and also has the layout button and the [click preview](../guide/presenter-mode.md#click-preview). A `layers/custom-nav-controls.ts` adds buttons of your own at its end, see [Global layers](../features/global-layers.md). The fullscreen button is left out where the page may not go fullscreen: in an iframe without `allow="fullscreen"`, and on an iPhone. `f` does nothing there. +The bar at the bottom left has buttons for fullscreen, previous, next, overview, dark mode, drawing, presenter mode, info, sync mode, settings and a counter. A deck with `languages` also has a language button before the settings, see [One deck in several languages](../features/interface-language.md#one-deck-in-several-languages). The bar shows when the mouse is there. `navPosition` in the headmatter puts it in another corner, or in the middle of the top or bottom edge, see [Headmatter and frontmatter](./headmatter.md#the-deck-and-its-look), and a viewer can move it from the settings menu or drag it by the grip at its start to one of the six places. On the presenter page the bar stays where it is and also has the layout button and the [click preview](../guide/presenter-mode.md#click-preview). A `layers/custom-nav-controls.ts` adds buttons of your own at its end, see [Global layers](../features/global-layers.md). The fullscreen button is left out where the page may not go fullscreen: in an iframe without `allow="fullscreen"`, and on an iPhone. `f` does nothing there. @@ -30,6 +31,8 @@ The settings button (More Options) opens the same menu as in Slidev: Invert, the Nav Bar Position is slide.ng's own. It is a small picture of the page with the six places of `navPosition`. Choosing a place moves the bar there at once, with its menus, and wins over the headmatter in this browser for this deck. Deck Default, or a double click on the title, forgets the choice, so the bar follows the headmatter again, also when the author changes it later. The arrow keys move through the places. In a right-to-left deck the picture is mirrored like the bar, and each place is named by where it is on the screen. +The bar can also be dragged by the grip at its start (not on the presenter page). While dragging, the page shows the six places and the one under the pointer lights up; dropping there is the same as choosing it in the menu. Escape, or a drop outside the page, leaves the bar where it was. When the bar is out of sight, the right-click menu has Show Navigation Bar, which shows it for a few seconds, and, once a place was chosen, Reset Navigation Bar Position, which goes back to the deck's own place. + Right click opens a menu with the same actions. Hold Shift while right clicking for the browser's own menu. From the keyboard, Shift+F10 or the menu key opens it with the focus on its first item; the arrow keys, Home, End and Tab move between the items, Enter or Space runs one, and Escape closes it and gives the focus back. While the menu is open the deck's keys do nothing. Click the dark area beside the slide: the right half goes to the next click, the left half to the previous one. ## Touch diff --git a/src/content/features/context-menu.md b/src/content/features/context-menu.md index d687f74..aaf6d99 100644 --- a/src/content/features/context-menu.md +++ b/src/content/features/context-menu.md @@ -7,6 +7,8 @@ description: The right-click menu, and how to turn it off or add to it. A right click on a slide opens a menu with the same actions as the bar. Hold Shift while right clicking for the browser's own menu. +When the navigation bar is out of sight, the menu also has Show Navigation Bar, which shows it for a few seconds. Once a viewer moved the bar, Reset Navigation Bar Position puts it back in the deck's own place. See [Shortcuts](../built-in/shortcuts.md#mouse). + ```md From 096f45d7c2bf0985287ff6af3aebdfdbd29eaa2e Mon Sep 17 00:00:00 2001 From: erkamyaman Date: Sun, 1 Nov 2026 15:38:41 +0300 Subject: [PATCH 3/3] docs: add upgrading from 2.x to 3.0 --- src/content/getting-started/install.md | 2 +- src/content/migrating/upgrading-to-3.md | 29 +++++++++++++++++++++++++ src/content/welcome.md | 2 +- src/ngmd.config.ts | 6 +++-- 4 files changed, 35 insertions(+), 4 deletions(-) create mode 100644 src/content/migrating/upgrading-to-3.md diff --git a/src/content/getting-started/install.md b/src/content/getting-started/install.md index 0a09cfb..a1a1793 100644 --- a/src/content/getting-started/install.md +++ b/src/content/getting-started/install.md @@ -5,7 +5,7 @@ description: Requirements and how to get slide.ng running today. # Install -These pages describe slide.ng 2.0. The commands below install the newest version. A deck that uses 1.x keeps working with it: to move it to 2.0, read [Upgrading from 1.x to 2.0](../migrating/upgrading-to-2.md), or pin the old version with `npm install -D @slide-ng/core@^1`. +These pages describe slide.ng 3.0. The commands below install the newest version. A deck that uses 2.x keeps working with it: to move it to 3.0, read [Upgrading from 2.x to 3.0](../migrating/upgrading-to-3.md), or pin the old version with `npm install -D @slide-ng/core@^2`. ## Requirements diff --git a/src/content/migrating/upgrading-to-3.md b/src/content/migrating/upgrading-to-3.md new file mode 100644 index 0000000..1477dfe --- /dev/null +++ b/src/content/migrating/upgrading-to-3.md @@ -0,0 +1,29 @@ +--- +title: Upgrading from 2.x to 3.0 +description: How to move a deck from slide.ng 2.x to 3.0, and the changes that can alter a deck that 2.x showed correctly. +--- + +# Upgrading from 2.x to 3.0 + +slide.ng 3.0 needs the same Node (22.22.3 or newer) and the same Angular (22.2) as 2.x. Update the package in the deck's folder: + +```sh +npm install -D @slide-ng/core@^3.0.0 +npx slide-ng dev +``` + +Most decks need no change. 3.0 is a major version because of the new [deck browser](../features/deck-browser.md), which changes what a few keys and links do. + +## Changes that can alter a deck + +- A click on a link to another site, on a slide, opens it in the deck browser instead of a new browser tab. Cmd, Ctrl, Shift or Alt with the click, or a middle click, still opens a real tab. To keep the 2.x behaviour, add `browser: { links: false }` to the headmatter. `browser: false` removes the deck browser altogether. +- `b` on the slide page opens and closes the deck browser. A `setup/shortcuts.ts` that used `b` for something else should pick another key, or the deck can set `browser: false`. +- In fullscreen, Chrome and Edge give the deck the Escape key, so the first Escape closes the deck browser and the next one leaves fullscreen. These browsers then say "Press and hold Esc to exit full screen". Other browsers leave fullscreen at once, as before. `browser: false` keeps the 2.x fullscreen. +- `slide-ng dev` on your machine opens one more port on `127.0.0.1`, for the deck browser's proxy. Not with `--remote`. + +## What is new + +The full list is in the [release notes](https://github.com/slide-ng/slide.ng/blob/main/CHANGELOG.md). + +- The [deck browser](../features/deck-browser.md): tabs, search, bookmarks, a start page with a clock and weather, and a proxy in the dev server so sites that refuse framing still show inside the deck. +- The navigation bar can be dragged by its grip to one of its six places, and the right-click menu can show it or reset its place. See [Shortcuts](../built-in/shortcuts.md#mouse). diff --git a/src/content/welcome.md b/src/content/welcome.md index a177be9..27544b5 100644 --- a/src/content/welcome.md +++ b/src/content/welcome.md @@ -50,6 +50,6 @@ Every page that shows a deck embeds a real build of it. You can also open them d -These pages describe slide.ng 2.0, which is on npm as `@slide-ng/core`. A deck made with 1.x: read [Upgrading from 1.x to 2.0](./migrating/upgrading-to-2.md). Some Slidev features are missing, and the [list of what is not supported](./migrating/not-supported.md) is kept honest. +These pages describe slide.ng 3.0, which is on npm as `@slide-ng/core`. A deck made with 2.x: read [Upgrading from 2.x to 3.0](./migrating/upgrading-to-3.md); with 1.x, first [Upgrading from 1.x to 2.0](./migrating/upgrading-to-2.md). Some Slidev features are missing, and the [list of what is not supported](./migrating/not-supported.md) is kept honest. diff --git a/src/ngmd.config.ts b/src/ngmd.config.ts index 7bfe8cf..40d679c 100644 --- a/src/ngmd.config.ts +++ b/src/ngmd.config.ts @@ -275,7 +275,8 @@ const config: NgmdConfig = { {label: 'Side editor', href: '/features/side-editor'}, {label: 'Drawing', href: '/features/drawing'}, {label: 'Recording', href: '/features/recording'}, - {label: 'Context menu', href: '/features/context-menu'}, + {label: 'Context menu', href: '/features/context-menu', status: 'updated'}, + {label: 'Deck browser', href: '/features/deck-browser', status: 'new'}, {label: 'Interface language', href: '/features/interface-language', status: 'new'}, {label: 'Loading pictures ahead', href: '/features/preload-images', status: 'new'}, ], @@ -325,7 +326,8 @@ const config: NgmdConfig = { { label: 'Migrating', items: [ - {label: 'Upgrading from 1.x', href: '/migrating/upgrading-to-2', status: 'new'}, + {label: 'Upgrading from 2.x', href: '/migrating/upgrading-to-3', status: 'new'}, + {label: 'Upgrading from 1.x', href: '/migrating/upgrading-to-2'}, {label: 'What differs from Slidev', href: '/migrating/from-slidev'}, {label: 'Not supported', href: '/migrating/not-supported'}, ],