Update Docs with Release 1.18 (#674)

* Stashed dynamic SSH profiles doc

* Add portable mode docs to release branch 1.18 (#655)

* added first draft of docs

* changed headings and subheadings

* Reword, add an Upgrading section

---------

Co-authored-by: Dustin Howett <duhowett@microsoft.com>

* Retool the portable mode documentation to explain our distributions (#656)

* Retool portable mode to be 'distributions'

* Fix warnings

* add preinstallation to the feature matrix

* add dci to matrix

* reword

* couple more notes

* better version note

* Use a data matrix table, re-alt-text the portable mode image

* add distributions to the toc

* address L's feedbacc

* Document 'activeOnly' value for 'showCloseButton' property. (#660)

* Shelfing read-only mode docs until it goes in a future release (#653)

* Added maximum history size (#657)

* added maximum history size

* empty commit to poke the bot

* Document 'activeOnly' value for 'showCloseButton' property.

---------

Co-authored-by: Christopher Nguyen <91625426+nguyen-dows@users.noreply.github.com>

* Add a small section on tab tearout in the overview page (#666)

* Shelfing read-only mode docs until it goes in a future release (#653)

* Added maximum history size (#657)

* added maximum history size

* empty commit to poke the bot

* initial commit

* added preview links and small grammatical fixes

* added important preview flag

* moved Important flag to the end of the section to fit Actions docs

* omit unrelated changes that got pulled in from master

* omit actions and profiles changes

* Add preview text and re-add missing enableReadOnlyMode docs (#673)

* add preview text and readd enableReadOnlyMode that was lost in the most recent commit

* add preview text for activeOnly value in showCloseButton property docs

---------

Co-authored-by: Dustin Howett <duhowett@microsoft.com>
Co-authored-by: kovdu <koen.vandurme@gmail.com>

TerminalDocs/TOC.yml

@@ -4,6 +4,8 @@
       href: index.md
     - name: Install
       href: install.md
+    - name: Distribution Types
+      href: distributions.md
     - name: Customize settings
       items:
         - name: Startup

TerminalDocs/customize-settings/actions.md

@@ -858,6 +858,30 @@ You can mark a pane as read-only, which will prevent input from going into the t
 { "command": "toggleReadOnlyMode" }
 ```
 
+You can enable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `enableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "enableReadOnlyMode" }
+```
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+You can disable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `disableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "disableReadOnlyMode" }
+```
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ### Split a pane
 
 This halves the size of the active pane and opens another. Without any arguments, this will open the default profile in the new pane. If an action is not specified, the default profile's equivalent setting will be used.

TerminalDocs/customize-settings/themes.md

@@ -193,12 +193,16 @@ Configures how the "close" button on the tab should appear. This accepts the fol
 * `"always"`: Always show tab close buttons.
 * `"hover"`: Show the tab close button on the active tab, and any tabs that are hovered with the mouse.
 * `"never"`: Never show tab close buttons. This also disables the ability to close the tab with the middle mouse button.
+* `"activeOnly"`: Show the tab close button on the active tab only.
+
+> [!IMPORTANT]
+> The `"activeOnly"` value is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
 
 **Property name:** `showCloseButton`
 
 **Necessity:** Optional
 
-**Accepts:** `"always"`, `"hover"`, `"never"`
+**Accepts:** `"always"`, `"hover"`, `"never"`, `"activeOnly"`
 
 **Default value:** `"always"`
 

TerminalDocs/distributions.md

@@ -0,0 +1,102 @@
+---
+title: Windows Terminal Distribution Types
+description: Learn how to use the different distributions of Windows Terminal.
+author: nguyen-dows
+ms.author: chrnguyen
+ms.date: 04/10/2023
+ms.topic: how-to 
+---
+
+# Windows Terminal Distribution Types
+
+Windows Terminal is distributed via [GitHub releases] in a variety of formats:
+
+- Packaged, or "MSIX bundle"
+    - This is the oldest and best-supported distribution of Windows Terminal.
+    - The packaged distribution can be installed via the `.msixbundle` file provided on the [GitHub releases] page or
+      through the Microsoft Store ([Stable](https://aka.ms/terminal), [Preview](https://aka.ms/terminal-preview)).
+    - Installation via MSIX bundle may require network connectivity to download dependency packages from the Store.
+    - When installed via MSIX bundle, Terminal will receive automatic updates through the Store.
+- Preinstallation Kit
+    - A [preinstallation kit] is available for system integrators and OEMs interested in preinstalling Windows Terminal
+      on a Windows image.
+    - More information is available in the [DISM documentation on preinstallation]. Users who do not intend to
+      preinstall Windows Terminal should continue using the Packaged distribution.
+    - When installed via preinstallation kit, Terminal will receive automatic updates through the Store.
+- Unpackaged, or "ZIP" (new in 1.17 stable)
+    - This distribution method was not officially supported until stable channel version 1.17.
+    - The unpackaged distribution does not receive automatic updates, which puts you in control of exactly when new
+      versions are installed.
+- Portable
+    - A variant of the unpackaged distribution, where Terminal stores its settings in a nearby directory.
+    - [Learn more about configuring Portable mode.](#windows-terminal-portable)
+
+## Distribution feature comparison
+
+|                                            | Packaged                 | Preinstallation Kit | Unpackaged       | Portable                      |
+| ------------------------------------------ | ------------------------ | ------------------- | ---------------- | ----------------------------- |
+| **Automatic updates**                      | ✅                       | ✅                  | ❌               | ❌                            |
+| **Automatic architecture selection**       | ✅                       | ✅                  | ❌               | ❌                            |
+| **Can be set as your default terminal**    | ✅                       | ✅                  | ❌               | ❌                            |
+| **"Open in Terminal" context menu**        | ✅                       | ✅                  | ❌               | ❌                            |
+| **Automatic start on login option**        | ✅                       | ✅                  | _manual_         | _manual_                      |
+| **Double-click installation**              | ✅                       | ❌                  | ❌               | ❌                            |
+| **Installation on non-networked machines** | ❌                       | ✅                  | ✅               | ✅                            |
+| **Preinstallation in a Windows image**     | ❌                       | ✅                  | _as plain files_ | _as plain files_              |
+| **User-controlled installation path**      | ❌                       | ❌                  | ✅               | ✅                            |
+| **Double-click activatable**               | ❌                       | ❌                  | ✅               | ✅                            |
+| **Settings storage location**              | User folder, per package | (same as packaged)  | `%LOCALAPPDATA%` | Next to `WindowsTerminal.exe` |
+
+## Windows Terminal Portable
+
+As of stable channel version 1.17, Windows Terminal supports being deployed in ["Portable mode"]. Portable mode ensures
+that all data created and maintained by Windows Terminal is saved next to the application so that it can be more easily
+moved across different environments.
+
+Portable mode is supported by the unpackaged "ZIP" distribution.
+
+This is an officially-supported mode of execution where Windows Terminal stores its settings in a `settings` folder next
+to `WindowsTerminal.exe`.
+
+Portable mode is not supported in the packaged or preinstallation kit distributions of Windows Terminal.
+
+### Why use Portable mode?
+
+The unpackaged and portable mode distributions of Windows Terminal allow you to use Terminal without installing it
+globally, e.g. on systems where you may not have permission to install MSIX packages or download software from the
+Microsoft Store.
+
+Portable mode allows you to carry around or archive a preconfigured installation of Windows Terminal and run it from
+a network share, cloud drive or USB flash drive. Any such installation is self-contained and will not interfere with
+other installed distributions of Windows Terminal.
+
+### Enabling Portable mode
+
+Portable mode needs to be enabled manually. After unzipping the Windows Terminal download, create a file named `.portable` next to `WindowsTerminal.exe`.
+
+> [!NOTE]
+> Windows Terminal will not automatically reload its settings when you create the portable mode marker file.
+> This change will only apply after you relaunch Terminal.
+
+Windows Terminal will automatically create a directory named `settings` in which it will store both settings and runtime
+state such as window layouts.
+
+![Windows Terminal portable mode disclaimer example](./images/portable-mode.png)
+
+### Disabling Portable mode
+
+You can restore Portable mode unpackaged installation to its original configuration, where settings are stored in
+`%LOCALAPPDATA%\Microsoft\Windows Terminal`, by removing the `.portable` marker file from the directory containing
+`WindowsTerminal.exe`.
+
+If you wish to reenable portable mode, you can create a new `.portable` marker file next to `WindowsTerminal.exe`.
+
+### Upgrading a Portable mode Install
+
+You can upgrade a portable mode installation of Windows Terminal by moving the `.portable` marker file and the
+`settings` directory to a newly-extracted unpackaged version of Windows Terminal.
+
+["Portable mode"]: https://en.wikipedia.org/wiki/Portable_application
+[GitHub releases]: https://github.com/microsoft/terminal/releases
+[preinstallation kit]: /windows/msix/desktop/deploy-preinstalled-apps
+[DISM documentation on preinstallation]: /windows-hardware/manufacture/desktop/preinstall-apps-using-dism

TerminalDocs/index.md

@@ -1,9 +1,9 @@
 ---
 title: An overview on Windows Terminal
 description: Learn about Windows Terminal and how it can improve your command line workflow.
-author: cinnamon-msft
-ms.author: cinnamon
-ms.date: 09/22/2020
+author: nguyen-dows
+ms.author: chrnguyen
+ms.date: 05/17/2023
 ms.topic: overview
 ---
 
@@ -25,6 +25,19 @@ Windows Terminal is a modern host application for the command-line shells you al
 
 Any application that has a command line interface can be run inside Windows Terminal. This includes everything from PowerShell and Command Prompt to Azure Cloud Shell and any WSL distribution such as Ubuntu or Oh-My-Zsh.
 
+## Tab tearout ([Preview](https://aka.ms/terminal-preview))
+
+You can tear out tabs in Windows Terminal and create new windows.
+
+![Windows Terminal tab tearout](./images/tear-tab.gif)
+
+You can also drag and drop tabs into existing windows.
+
+![Dragging and dropping tabs into Terminal windows](./images/attach-tab.gif)
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Customized schemes and configurations
 
 You can configure your Windows Terminal to have a variety of color schemes and settings. To learn how to customize your prompt with cool themes, see [Tutorial: Set up a custom prompt for PowerShell or WSL with Oh My Posh](./tutorials/custom-prompt-setup.md) To learn how to make your own color scheme, visit the [Color schemes page](./customize-settings/color-schemes.md).

TerminalDocs/panes.md

@@ -224,6 +224,32 @@ You can toggle read-only mode on a pane with the `toggleReadOnlyMode` command.
 { "command": "toggleReadOnlyMode" }
 ```
 
+You can enable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `enableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "enableReadOnlyMode" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
+You can disable read-only mode on a pane. This works similarly to toggling, however, will not switch state if triggered again.
+
+**Command name:** `disableReadOnlyMode`
+
+**Default bindings:**
+
+```json
+{ "command": "disableReadOnlyMode" }
+```
+
+> [!IMPORTANT]
+> This feature is only available in [Windows Terminal Preview](https://aka.ms/terminal-preview).
+
 ## Customizing panes using key bindings
 
 You can customize what opens inside a new pane depending on your custom key bindings.

TerminalDocs/tutorials/ssh.md

@@ -10,7 +10,7 @@ ms.topic: tutorial
 
 # Tutorial: SSH in Windows Terminal
 
-Windows has a built-in SSH client that you can use in Windows Terminal. In this tutorial, you'll learn how to set up a profile in Windows Terminal that uses SSH.
+Windows has a built-in SSH client that you can use in Windows Terminal. In this tutorial, you'll learn how to set up a profile in Windows Terminal that uses SSH. Note that this feature is in preview.
 
 ## Access Windows SSH Client
 
@@ -20,6 +20,9 @@ By default, the OpenSSH client will be located in the directory: `C:\Windows\Sys
 
 ![OpenSSH feature in Windows Settings](../images/ssh-optonialfeatures.png)
 
+> [!NOTE]
+> Windows Terminal version 1.XX+ can dynamically generate profiles to connect to the SSH hosts within your [OpenSSH config file](https://man.openbsd.org/ssh_config).
+
 ## Create a profile
 
 You can start an SSH session in your command prompt by executing `ssh user@machine` and you will be prompted to enter your password. You can create a Windows Terminal profile that does this on startup by adding the `commandline` setting to a profile in your [settings.json file](../install.md#settings-json-file) inside the `list` of profile objects.