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) diff --git a/README.md b/README.md index 7831247..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 @@ -116,6 +120,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_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 | @@ -126,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/docs/index.md b/plex-guide/docs/index.md index 7d4be9b..cdf7dbc 100644 --- a/plex-guide/docs/index.md +++ b/plex-guide/docs/index.md @@ -437,6 +437,109 @@ If your smart TV struggles with Plex, consider a dedicated streaming device. The --- +{% 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: + +- **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 + +{% endif %} +{% if has_4k_content | default(true) %} + +--- + +## 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..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: @@ -69,6 +71,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_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 21f0726..38ba0ed 100755 --- a/plex-guide/setup.sh +++ b/plex-guide/setup.sh @@ -126,6 +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_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" @@ -156,6 +158,8 @@ 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 update_config "server_cost" "$server_cost"