From cc8569210b6c2876628c2d3de5e4a88f9a773503 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Thu, 12 Mar 2026 00:02:55 -0500 Subject: [PATCH 1/4] feat: add direct play and 4K streaming sections Adds two new sections to the plex guide template: - Direct Play: general guidance on getting the best quality - 4K Streaming: specific 4K considerations, device compatibility, bandwidth Controlled by has_4k_content variable (default: true). --- README.md | 1 + plex-guide/docs/index.md | 100 +++++++++++++++++++++++++++++++++++ plex-guide/mkdocs.sample.yml | 1 + plex-guide/setup.sh | 2 + 4 files changed, 104 insertions(+) diff --git a/README.md b/README.md index 7831247..f0ee64e 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,7 @@ Set to `true` to show the section, `false` to hide it. | `guide_url` | `""` | Public URL for the guide | | `has_plex_pass` | `true` | Plex Pass features section | | `has_plex_home` | `false` | Plex Home notes | +| `has_4k_content` | `true` | 4K direct play optimization guide | | `has_migration` | `false` | Watch history migration section | | `show_costs` | `false` | Server cost information | | `server_cost` | `""` | Monthly cost string | diff --git a/plex-guide/docs/index.md b/plex-guide/docs/index.md index 7d4be9b..8a1f332 100644 --- a/plex-guide/docs/index.md +++ b/plex-guide/docs/index.md @@ -437,6 +437,106 @@ If your smart TV struggles with Plex, consider a dedicated streaming device. The --- +{% if has_4k_content | default(true) %} +## Direct Play (Best Quality) + +**Direct play** means your device plays the video file exactly as-is, with no conversion by the server. This always gives you the best experience: + +- **Best quality** — you see exactly what was encoded +- **No server load** — the server just sends the file +- **Faster start** — no waiting for the server to process + +When direct play isn't possible, the server **transcodes** (converts) the video in real-time, which uses server resources and can reduce quality. + +### How to Get Direct Play + +#### Set Quality to Maximum/Original + +The most common reason for unnecessary transcoding is the quality setting being too low. + +=== "On Your TV/Streaming Device" + + 1. Open the Plex app + 2. Go to **Settings** → **Video Quality** + 3. Set **Remote Streaming** to **Original** or **Maximum** + 4. Set **Home Streaming** to **Original** or **Maximum** + +=== "On Your Phone/Tablet" + + 1. Open Plex → **Settings** (gear icon) + 2. Tap **Quality** + 3. Set **Remote Streaming** to **Maximum** + 4. Set **Home Streaming** to **Maximum** + +#### Use the Native Plex App + +!!! warning "Web Browsers Force Transcoding" + Browsers (Chrome, Firefox, Safari) don't support most video codecs and will force the server to transcode. Always use the **native Plex app** on your device. + +#### Check if You're Direct Playing + +While watching a video: + +1. Press the **info** button (or tap **...** on mobile) +2. Look for **"Direct Play"** — this means no transcoding +3. If it says **"Transcode"**, something is preventing direct play + +Common reasons for transcoding: + +- Quality set below **Original/Maximum** (most common!) +- Watching in a web browser instead of the Plex app +- Device doesn't support the video codec (HEVC/H.265) +- Device doesn't support the audio codec — try switching to a compatible audio track +- Image-based subtitles (PGS/ASS) being burned in — try SRT subtitles instead + +--- + +## 4K Streaming + +4K movies look incredible, but they're **massive files** — a single 4K movie can be 50-80 GB. This creates unique challenges. + +!!! danger "Never Transcode 4K" + Transcoding 4K defeats the purpose — you get **worse quality** than just watching the 1080p version, while also hammering the server. If your device can't direct play 4K, watch the 1080p version instead. + +### Can Your Device Handle 4K? + +| Device | 4K Direct Play | HDR | Lossless Audio | +|--------|:-:|:-:|:-:| +| **Nvidia Shield TV Pro** | Yes | Yes | Yes | +| **Apple TV 4K** | Yes | Yes | Partial | +| **Fire TV Stick 4K Max** | Yes | Yes | No | +| **Onn 4K Google TV** | Yes | Yes | No | +| **Most Smart TVs** | Varies | Varies | No | +| **Web Browser** | No | No | No | + +### Bandwidth Requirements + +4K content requires significantly more internet speed than HD: + +| Quality | Minimum Speed Needed | +|---------|---------------------| +| 1080p | 10-20 Mbps | +| 4K SDR | 25-40 Mbps | +| 4K HDR | 40-80 Mbps | +| 4K Remux | 80-120+ Mbps | + +Test your speed at [fast.com](https://fast.com). If your speed is below the requirement, Plex will transcode the video automatically — and for 4K, that means worse quality than 1080p. + +!!! tip "Use Ethernet for 4K" + WiFi is unreliable for 4K streaming. A wired ethernet connection to your streaming device is the single best improvement you can make. + +### Quick Reference + +| Do This | Not This | +|---------|----------| +| Use the native Plex app | Watch in a web browser | +| Set quality to **Original/Maximum** | Leave it on "auto" or a lower setting | +| Use ethernet for 4K | Rely on WiFi for large files | +| Watch 1080p if 4K transcodes | Force 4K on a device that can't handle it | + +{% endif %} +--- + ## More Help | Resource | Link | diff --git a/plex-guide/mkdocs.sample.yml b/plex-guide/mkdocs.sample.yml index 975f913..a52c8bc 100644 --- a/plex-guide/mkdocs.sample.yml +++ b/plex-guide/mkdocs.sample.yml @@ -69,6 +69,7 @@ extra: guide_url: "" # Public URL for this guide has_plex_pass: true # Whether your server has a Plex Pass has_plex_home: false # Whether you use Plex Home for some users + has_4k_content: true # Whether to show 4K/direct play optimization section has_migration: false # Whether you offer watch history migration show_costs: false # Whether to show server cost information server_cost: "" # Monthly server cost (e.g., "~$50/month") diff --git a/plex-guide/setup.sh b/plex-guide/setup.sh index 21f0726..180a4a4 100755 --- a/plex-guide/setup.sh +++ b/plex-guide/setup.sh @@ -126,6 +126,7 @@ fi prompt_bool has_plex_pass "Does your server have a Plex Pass?" "true" prompt_bool has_plex_home "Do you use Plex Home for some users?" "false" +prompt_bool has_4k_content "Show 4K/direct play optimization section?" "true" prompt_bool has_migration "Do you offer watch history migration?" "false" prompt_bool show_costs "Show server cost information?" "false" @@ -156,6 +157,7 @@ update_config "has_guide_url" "$has_guide_url" true update_config "guide_url" "$guide_url" update_config "has_plex_pass" "$has_plex_pass" true update_config "has_plex_home" "$has_plex_home" true +update_config "has_4k_content" "$has_4k_content" true update_config "has_migration" "$has_migration" true update_config "show_costs" "$show_costs" true update_config "server_cost" "$server_cost" From b596d8f4d499f2c763e0fe336c42fee3dd24dec5 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Thu, 12 Mar 2026 00:11:25 -0500 Subject: [PATCH 2/4] feat: split has_4k_content into distinct direct play and 4K controls Add has_direct_play variable to independently toggle the direct play optimization section from the 4K streaming section. --- README.md | 3 ++- plex-guide/docs/index.md | 5 ++++- plex-guide/mkdocs.sample.yml | 3 ++- plex-guide/setup.sh | 4 +++- 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f0ee64e..0421edd 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,8 @@ Set to `true` to show the section, `false` to hide it. | `guide_url` | `""` | Public URL for the guide | | `has_plex_pass` | `true` | Plex Pass features section | | `has_plex_home` | `false` | Plex Home notes | -| `has_4k_content` | `true` | 4K direct play optimization guide | +| `has_direct_play` | `true` | Direct play optimization guide | +| `has_4k_content` | `true` | 4K streaming section | | `has_migration` | `false` | Watch history migration section | | `show_costs` | `false` | Server cost information | | `server_cost` | `""` | Monthly cost string | diff --git a/plex-guide/docs/index.md b/plex-guide/docs/index.md index 8a1f332..cdf7dbc 100644 --- a/plex-guide/docs/index.md +++ b/plex-guide/docs/index.md @@ -437,7 +437,7 @@ If your smart TV struggles with Plex, consider a dedicated streaming device. The --- -{% if has_4k_content | default(true) %} +{% if has_direct_play | default(true) %} ## Direct Play (Best Quality) **Direct play** means your device plays the video file exactly as-is, with no conversion by the server. This always gives you the best experience: @@ -489,6 +489,9 @@ Common reasons for transcoding: - Device doesn't support the audio codec — try switching to a compatible audio track - Image-based subtitles (PGS/ASS) being burned in — try SRT subtitles instead +{% endif %} +{% if has_4k_content | default(true) %} + --- ## 4K Streaming diff --git a/plex-guide/mkdocs.sample.yml b/plex-guide/mkdocs.sample.yml index a52c8bc..e64e58f 100644 --- a/plex-guide/mkdocs.sample.yml +++ b/plex-guide/mkdocs.sample.yml @@ -69,7 +69,8 @@ extra: guide_url: "" # Public URL for this guide has_plex_pass: true # Whether your server has a Plex Pass has_plex_home: false # Whether you use Plex Home for some users - has_4k_content: true # Whether to show 4K/direct play optimization section + has_direct_play: true # Whether to show direct play optimization section + has_4k_content: true # Whether to show 4K streaming section has_migration: false # Whether you offer watch history migration show_costs: false # Whether to show server cost information server_cost: "" # Monthly server cost (e.g., "~$50/month") diff --git a/plex-guide/setup.sh b/plex-guide/setup.sh index 180a4a4..38ba0ed 100755 --- a/plex-guide/setup.sh +++ b/plex-guide/setup.sh @@ -126,7 +126,8 @@ fi prompt_bool has_plex_pass "Does your server have a Plex Pass?" "true" prompt_bool has_plex_home "Do you use Plex Home for some users?" "false" -prompt_bool has_4k_content "Show 4K/direct play optimization section?" "true" +prompt_bool has_direct_play "Show direct play optimization section?" "true" +prompt_bool has_4k_content "Show 4K streaming section?" "true" prompt_bool has_migration "Do you offer watch history migration?" "false" prompt_bool show_costs "Show server cost information?" "false" @@ -157,6 +158,7 @@ update_config "has_guide_url" "$has_guide_url" true update_config "guide_url" "$guide_url" update_config "has_plex_pass" "$has_plex_pass" true update_config "has_plex_home" "$has_plex_home" true +update_config "has_direct_play" "$has_direct_play" true update_config "has_4k_content" "$has_4k_content" true update_config "has_migration" "$has_migration" true update_config "show_costs" "$show_costs" true From b5c81c2c192bf53d0d356376b84eed939038c63c Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Thu, 12 Mar 2026 00:15:20 -0500 Subject: [PATCH 3/4] docs: add theme features reference and CI badges to README Add build/lint/preview badges, document each Material for MkDocs theme feature with descriptions. Add navigation.instant and content.code.annotate to the template. --- README.md | 19 +++++++++++++++++++ plex-guide/mkdocs.sample.yml | 2 ++ 2 files changed, 21 insertions(+) diff --git a/README.md b/README.md index 0421edd..27765e7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # docs-templates +[![Build Plex Guide](https://github.com/baker-scripts/docs-templates/actions/workflows/build.yml/badge.svg)](https://github.com/baker-scripts/docs-templates/actions/workflows/build.yml) +[![Lint](https://github.com/baker-scripts/docs-templates/actions/workflows/lint.yml/badge.svg)](https://github.com/baker-scripts/docs-templates/actions/workflows/lint.yml) +[![Live Preview](https://img.shields.io/badge/Live_Preview-GitHub_Pages-blue)](https://baker-scripts.github.io/docs-templates/plex/) + MkDocs documentation templates with variable substitution. Fork, customize, and deploy your own documentation site. ## Available Templates @@ -128,6 +132,21 @@ Templates use [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io Conditional sections use `{% if feature_flag %}...{% endif %}` to show/hide content based on your configuration. +## Theme Features + +The template uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) with a dark-first theme (slate) and light mode toggle. The following features are enabled: + +| Feature | Description | +|---------|-------------| +| `navigation.sections` | Groups top-level sections in the sidebar with visible headers | +| `navigation.instant` | Loads pages via XHR without full page reload for faster navigation | +| `toc.follow` | Automatically scrolls the table of contents sidebar to highlight the active heading | +| `search.suggest` | Shows search term suggestions as you type in the search bar | +| `search.highlight` | Highlights matching search terms on the page after navigating from search results | +| `content.code.copy` | Adds a copy-to-clipboard button on all code blocks | +| `content.code.annotate` | Enables numbered annotations inside code blocks with expandable tooltips | +| `content.tabs.link` | Syncs tab selection across all tabbed content blocks on the page | + ## Deployment ### GitHub Pages (automatic) diff --git a/plex-guide/mkdocs.sample.yml b/plex-guide/mkdocs.sample.yml index e64e58f..f73a21e 100644 --- a/plex-guide/mkdocs.sample.yml +++ b/plex-guide/mkdocs.sample.yml @@ -22,10 +22,12 @@ theme: name: Switch to dark mode features: - navigation.sections + - navigation.instant - toc.follow - search.suggest - search.highlight - content.code.copy + - content.code.annotate - content.tabs.link plugins: From 7c4d931ea822b3883fdb45c016dd479db1581b37 Mon Sep 17 00:00:00 2001 From: bakerboy448 <55419169+bakerboy448@users.noreply.github.com> Date: Thu, 12 Mar 2026 01:58:30 -0500 Subject: [PATCH 4/4] fix: markdownlint blank lines around fenced code blocks --- CLAUDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c7ae042..28b26a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,6 +21,7 @@ MkDocs documentation templates with `mkdocs-macros-plugin` for Jinja2 variable s ## Development - Build: use a venv or Docker, never system-wide pip + ```bash cd plex-guide python3 -m venv .venv @@ -28,6 +29,7 @@ MkDocs documentation templates with `mkdocs-macros-plugin` for Jinja2 variable s cp mkdocs.sample.yml mkdocs.yml .venv/bin/mkdocs build ``` + - Lint: `npx markdownlint-cli2 "**/*.md"` and `shellcheck plex-guide/setup.sh` - CI runs markdownlint, shellcheck, yamllint on all PRs - GitHub Pages deploys from GHA workflow (plex guide at `/plex/` subpath)