{"id":25441916,"url":"https://github.com/mistercalvin/mkdocs-plex-guide-template-cf-pages","last_synced_at":"2025-07-27T14:08:12.351Z","repository":{"id":277959662,"uuid":"934035837","full_name":"MisterCalvin/mkdocs-plex-guide-template-cf-pages","owner":"MisterCalvin","description":"A customizable Plex documentation template built with Material for MkDocs. Automatically deploys to Cloudflare Pages and includes pre-built guides for common Plex topics like streaming quality, content requests, and troubleshooting.","archived":false,"fork":false,"pushed_at":"2025-02-17T21:29:47.000Z","size":5059,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-15T19:09:27.832Z","etag":null,"topics":["cloudflare-pages","mkdocs","plex-documentation","plex-guide","plex-server"],"latest_commit_sha":null,"homepage":"","language":"Markdown","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MisterCalvin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-17T06:59:19.000Z","updated_at":"2025-03-25T22:39:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"0c8446c2-70bc-4554-90eb-4a3f54b1dfd4","html_url":"https://github.com/MisterCalvin/mkdocs-plex-guide-template-cf-pages","commit_stats":null,"previous_names":["mistercalvin/mkdocs-plex-guide-template-cf-pages"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/MisterCalvin/mkdocs-plex-guide-template-cf-pages","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MisterCalvin%2Fmkdocs-plex-guide-template-cf-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MisterCalvin%2Fmkdocs-plex-guide-template-cf-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MisterCalvin%2Fmkdocs-plex-guide-template-cf-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MisterCalvin%2Fmkdocs-plex-guide-template-cf-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MisterCalvin","download_url":"https://codeload.github.com/MisterCalvin/mkdocs-plex-guide-template-cf-pages/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MisterCalvin%2Fmkdocs-plex-guide-template-cf-pages/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267368932,"owners_count":24076093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare-pages","mkdocs","plex-documentation","plex-guide","plex-server"],"created_at":"2025-02-17T13:16:00.087Z","updated_at":"2025-07-27T14:08:12.345Z","avatar_url":"https://github.com/MisterCalvin.png","language":"Markdown","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plex Documentation Guide\n\n![Login screen](.github/img/login_screen_ex.png)\n\nA standardized documentation template for your Plex server, built with Material for MkDocs and deployed via Cloudflare Pages. This template includes pre-built pages covering common Plex topics like streaming quality, content requests, transcoding, and more, all of which are protected via Plex OAuth so only your users can read them.\n\nThis documentation project contains the same content as [mkdocs-plex-guide-template](https://github.com/MisterCalvin/mkdocs-plex-guide-template), but with a different deployment configuration. To see an example of the docs, take a look at the GitHub Pages [example site](https://mistercalvin.github.io/mkdocs-plex-guide-template/).\n\n## ✨ Features\n- 📚 Pre-built pages for common Plex topics\n- 🔄 Automatic deployment via Cloudflare Pages\n- 🎨 Material for MkDocs theme with custom styling\n- 🔒 Docs are protected via Plex OAuth (only users with access to your Plex server can view)\n\n## Deployments\n\nThe project uses Cloudflare Pages' Git integration for automatic deployments. When you push to your configured branch (default: main), Cloudflare will:\n\n1. Detect the changes in your repository\n2. Pull the latest code\n3. Run the build command (`git fetch --unshallow \u0026\u0026 mkdocs build`)\n4. Deploy the built files to Cloudflare's global network\n\nEach commit creates a unique deployment with its own URL, and successful builds on the production branch are automatically published to your primary domain.\n\nFor more information about the Git integration and deployment process, see the [Cloudflare Pages Git Integration documentation](https://developers.cloudflare.com/pages/configuration/git-integration/).\n\n## 🔒 Security Considerations\n\n### Asset Access\nFor performance and resource optimization, certain static assets are intentionally excluded from authentication checks (defined in [`functions/_routes.json`](functions/_routes.json)). This means files in the following paths are publicly accessible:\n- `/assets/css/*`\n- `/assets/js/*`\n- `/assets/images/*`\n- `/assets/video/*`\n- Root-level CSS/JS files and favicons\n\nThis design choice:\n- Reduces authentication processing overhead\n- Minimizes API requests\n- Helps stay within Cloudflare Pages' [free tier limits](#-cloudflare-pages-free-tier-usage-limits) (100,000 requests/day)\n\n\u003e [!NOTE]\n\u003e While these assets are accessible without authentication, they are not easily discoverable unless someone knows the exact file paths. However, if your documentation includes sensitive images or media files, consider storing them in a different location or enabling authentication for specific asset paths.\n\n## Quick Links\n- [🚀 Getting Started](#-getting-started)\n- [⚙️ Configure Cloudflare Pages](#2-️-configure-cloudflare-pages)\n- [📄 MkDocs Configuration](#3--mkdocs-configuration)\n- [➕ Additional Steps](#4--additional-steps)\n- [🎨 Customization](#-customization)\n- [🔧 Troubleshooting](#-troubleshooting)\n- [💻 Cloudflare Pages Free Tier Usage Limits](#-cloudflare-pages-free-tier-usage-limits)\n- [📚 Resources](#-resources)\n\n## 🚀 Getting Started\n\n### 1. Create GitHub Repository\n1. Create a new repository from this template\n2. Clone your new repository locally\n3. Follow the steps below, then push your documentation to the repository\n\n### 2. ⚙️ Configure Cloudflare Pages\n\n1. Go to Cloudflare Dashboard → Compute (Workers) → Workers \u0026 Pages\n2. Click \"Create\" → \"Pages\" → \"Connect to Git\"\n3. Select your GitHub repository\n4. Configure build settings:\n   - Framework present: `None`\n   - Build command: `git fetch --unshallow \u0026\u0026 mkdocs build`\n   - Build output directory: `site`\n   - Root directory: (leave empty)\n   - Build comments: Enabled\n\n5. Add environment variables:\n\n\u003e [!WARNING]\n\u003e ### Secrets\n\u003e You can add your Secrets as Variables on the same page when configuring your build settings, but once your pages application is deployed be sure to go into \"Settings\" → \"Variables and Secrets\" and change your `PLEX_SERVER_ID, PLEX_CLIENT_ID, MKDOCS_GIT_COMMITTERS_APIKEY` variables to `Secret`, otherwise they will be printed as plaintext in any logs.\n\n   | Type | Name | Value | Description |\n   |------|------|-------|-------------|\n   | Text | `COOKIE_NAME` | plex_session | Name for the authentication cookie |\n   | Text | `DEBUG` | false | Enable debug logging |\n   | Secret | `PLEX_SERVER_ID` | Machine ID | Your Plex server's machine identifier ([see below](#finding-your-plex-server-id)) |\n   | Secret | `PLEX_CLIENT_ID` | UUID | Your generated application ID ([see below](#generating-a-plex-client-id)) |\n   | Secret | `MKDOCS_GIT_COMMITTERS_APIKEY` | GitHub Token | Optional: For showing git contributors ([see below](#github-fine-grained-access-token-optional)) |\n\n\u003e [!NOTE]\n\u003e The first deployment will fail, as `mkdocs.yml` contains placeholder values we need to update\n\u003e\n\u003e The failure occurs because we need to know the Cloudflare Pages domain (`your-project-name.pages.dev`) before we can properly configure `mkdocs.yml`. The recommended setup order is:\n\u003e\n\u003e 1. Connect your repository to Cloudflare Pages and attempt the first deployment\n\u003e 2. Note your assigned `*.pages.dev` domain\n\u003e 3. Update `mkdocs.yml` with the correct domain values\n\u003e 4. Push your changes to trigger a new deployment\n\u003e\n\u003e If you're experienced with Cloudflare Pages and already know your `*.pages.dev` domain (or are intend to use a [custom domain](#-custom-domain-optional)), you can update `mkdocs.yml` before connecting your repository.\n\n### 3. 📄 MkDocs Configuration\n\nThe [`mkdocs.yml`](mkdocs.yml) file controls your documentation settings. You'll need to update several values for your deployment:\n\n1. Basic Settings:\n```yaml\nsite_name: your-site-name  # e.g., guide.plex.yourdomain.com\nsite_url: https://your-domain.com\n```\n\n2. Theme Configuration:\n```yaml\ntheme:\n  logo: assets/images/plex-logo.webp  # Replace with your logo\n```\n\n3. Git Committers Plugin (if using):\n```yaml\nplugins:\n  - git-committers:\n      repository: YourUsername/your-repo-name\n      branch: main  # Or your default branch\n      exclude_committers:\n        - \"web-flow\"  # GitHub web UI edits\n        - \"actions-user\"  # GitHub Actions\n        - \"github-actions[bot]\"  # GitHub Actions bot\n      token: !ENV GITHUB_TOKEN\n```\n\n4. Social Links:\n```yaml\nextra:\n  social:\n    - icon: fontawesome/brands/github\n      link: https://github.com/yourusername\n      name: Your Name @ Github\n    - icon: fontawesome/brands/discord\n      link: https://your-discord-link\n      name: Discord Channel\n    - icon: fontawesome/solid/globe\n      link: https://your-website.com\n      name: Personal Website\n```\n\n5. Copyright Notice:\n```yaml\ncopyright: Copyright \u0026copy; 2025 Your Name\n```\n\n\u003e [!NOTE]\n\u003e The navigation structure (`nav:`) can also be customized to match your documentation needs. You can add, remove, or reorganize pages as needed.\n\u003e Check the MKDocs links in the [Resources](#-resources) section at the bottom for more information\n\n6. Trigger initial build and test:\n    - Push the updated mkdocs.yml to your repository to trigger a build\n    - Once deployed, visit your Pages URL (shown at the top of your project's dashboard as *.pages.dev)\n    - Confirm you're redirected to Plex login\n    - After logging in, verify you can access the documentation\n\n### 4. ➕ Additional Steps\n\n#### Finding Your Plex Server ID\nYou can find your Server ID by visiting:\n- `https://your-plex-server:32400/identity`\n- Look for the `machineIdentifier` field\n\n#### Generating a Plex Client ID\n1. Generate a UUID v4:\n   - You can use an online [UUID generator](https://www.uuidgenerator.net/)\n   - Or use this command:\n     ```bash\n     python3 -c 'import uuid; print(uuid.uuid4())'\n     ```\n2. Add the generated UUID as a Secret environment variable named `PLEX_CLIENT_ID` in your Pages settings\n\n#### GitHub Fine-Grained Access Token (Optional)\n\u003e [!NOTE]\n\u003e The git committers plugin is optional. If you don't need to show document contributors at the bottom of each documentation page, you can skip this step entirely.\n\n1. Navigate to your [Fine-grained Personal access tokens](https://github.com/settings/personal-access-tokens) (`GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens`)\n2. Click \"Generate new token\"\n3. Configure the token:\n   - Token name: \"Plex Guide (Git Committers API Key)\"\n   - Repository access: Select \"Only select repositories\"\n   - Select your documentation repository\n   - Permissions:\n     - Repository permissions:\n       - Contents: Read-only\n       - Metadata: Read-only\n4. Add the token as `MKDOCS_GIT_COMMITTERS_APIKEY` in your Pages environment variables\n\n## 🎨 Customization\n\n### Content Customization\nKey files to modify:\n- `docs/*.md` - Documentation pages\n- `docs/assets/css/extra.css` - [Custom admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions)\n- `docs/assets/` - Images, videos, Style Sheets, and JavaScript\n- `functions/` - Cloudflare Pages functions\n\n### 🔗 Custom Domain (Optional)\n1. Go to your Pages project → Settings → Custom domains\n2. Click \"Set up a custom domain\"\n3. Follow the prompts to add and verify your domain\n4. Once verified, your Plex auth and documentation will automatically use the new domain\n\n### Preview Deployments\n\nCloudflare Pages creates unique URLs for each deployment, including preview deployments from non-main branches. By default, these use the format `\u003chash\u003e.pages.dev`.\n\nFor convenience during development, it's recommended to set up a custom domain for your preview branch:\n\n1. Go to your Pages project → Settings → Custom domains\n2. Click \"Add custom domain\"\n3. Enter your preview domain (e.g., `dev.guide.plex.yourdomain.com`)\n4. Under \"Branch\", select your development branch (e.g., `development`)\n5. Follow the prompts to verify the domain\n\nThis avoids having to re-authenticate with Plex each time you deploy to a preview branch, as the authentication is tied to the domain. Without a custom preview domain, you would need to log in again for each new `\u003chash\u003e.pages.dev` URL.\n\n\u003e [!NOTE]\n\u003e ### Branch Domain Structure\n\u003e You can use different subdomains for different branches:\n\u003e - Production (main): `guide.plex.yourdomain.com`\n\u003e - Development: `dev.guide.plex.yourdomain.com`\n\u003e - Feature branches: `staging.guide.plex.yourdomain.com`\n\n### Authentication Page Styling\n\nThe login page can be customized by modifying two main files:\n\n1. Background Image: [`docs/assets/images/auth/bg.webp`](docs/assets/images/auth/bg.webp)\n   - Replace this file with your own background image\n   - Recommended size: 1080x1200px (will automatically fit different devices)\n   - Format: WebP preferred for optimal loading\n\n2. Styling: [`docs/assets/css/auth.css`](docs/assets/css/auth.css)\n   - Contains all styling for the authentication pages\n   - Customize colors, fonts, animations, and layout\n\n#### Removing the Background Image\n\nIf you prefer a solid color background, modify the CSS in [docs/assets/css/auth.css](docs/assets/css/auth.css):\n\n1. Add the base background color to the html element:\n```css\nhtml {\n  background: #282a2d;\n}\n\nbody {\n  font-family: -apple-system, system-ui, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  min-height: 100vh;\n  margin: 0;\n  background: #282a2d;  /* Solid color instead of image */\n  color: white;\n  -webkit-text-size-adjust: 100%;\n}\n```\n\n## 🔧 Troubleshooting\n\n### Viewing Logs\n\nTo view logs and debug authentication issues:\n\n1. Go to Cloudflare Dashboard → Compute (Workers) → Workers \u0026 Pages → Your Pages project\n2. From the \"Deployments\" tab, click on your latest deployment at the top of the page\n3. Click \"View details\"\n4. Navigate to the \"Functions\" tab\n5. Click \"Begin log stream\" to view real-time logs\n\nFor more detailed logging, set the `DEBUG` environment variable to `true` in your Pages settings. This will output additional information about:\n- Authentication attempts\n- Server access checks\n- Resource validation\n- Request processing\n\n\u003e [!WARNING]\n\u003e Environment variables require a new deployment to take effect. After enabling `DEBUG`, go to Deployments → Latest deployment → Click `...` next to \"View Details\" → \"Retry deployment\". Remember to redeploy again after setting `DEBUG` back to `false` to disable logging in production.\n\u003e\n\u003e Each deployment counts toward your free plan limit of [500 builds per month](#-cloudflare-pages-free-tier-usage-limits)\n\nTake a look at the Cloudflare Pages docs on [Debugging Pages](https://developers.cloudflare.com/pages/configuration/debugging-pages/) for more.\n\n### CSS/JS Changes Not Appearing\n\nIf changes to CSS or JavaScript files are not showing up after deployment:\n1. Go to Cloudflare Dashboard → Websites → Your domain → Caching\n2. Click \"Configuration\"\n3. Select \"Custom Purge\" and enter the paths to your CSS/JS files:\n    - `https://your-domain.com/assets/css/auth.css`\n    - `https://your-domain.com/assets/js/auth.js`\n    (Replace your-domain.com with your actual domain)\n\nThis will force Cloudflare to fetch the latest versions of these files.\n\n\u003e [!TIP]\n\u003e ### Browser Cache\n\u003e Sometimes your browser might cache CSS/JS files. If you're still not seeing changes after purging Cloudflare's cache, try a hard refresh (Ctrl+F5) in your browser.\n\n## 💻 Cloudflare Pages Free Tier Usage Limits\n\n### Free Plan Limits\n- **Functions Requests**: 100,000 per day (resets at midnight UTC)\n  - This includes any requests that go through authentication\n  - Static assets (CSS, images, etc.) are unlimited and free\n- **Builds**: 500 per month\n  - Each push to your repository counts as a build\n  - Builds timeout after 20 minutes\n- **Custom Domains**: 100 per project\n- **Files**: Maximum 20,000 files per site\n- **File Size**: 25 MiB per file\n\n\u003e [!TIP]\n\u003e ### Upgrading to Pro\n\u003e If you need higher limits, you can upgrade to Pro by:\n\u003e 1. Having any domain on Cloudflare with a Pro plan or higher\n\u003e 2. That domain doesn't need to use Pages - it just needs to be on a Pro plan\n\u003e\n\u003e See the [community discussion](https://community.cloudflare.com/t/how-to-buy-pro-plan-for-cf-pages/667975/5) for more details.\n\nFor more information, see:\n- [Cloudflare Pages Limits](https://developers.cloudflare.com/pages/platform/limits/)\n- [Static Asset Requests](https://developers.cloudflare.com/pages/functions/pricing/#static-asset-requests)\n- [Functions Invocation Routes](https://developers.cloudflare.com/pages/functions/routing/#functions-invocation-routes)\n\n## 📚 Resources\n\n### Documentation / Plugins\n- [Cloudflare Pages Docs - Overview](https://developers.cloudflare.com/pages/)\n- [Cloudflare Pages Docs - Add a custom domain to a branch](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/)\n- [Cloudflare Pages Docs - Preview deployments](https://developers.cloudflare.com/pages/configuration/preview-deployments/)\n- [Material for MkDocs - Getting started](https://squidfunk.github.io/mkdocs-material/getting-started/)\n- [MkDocs Plugins Catalog](https://github.com/mkdocs/catalog)\n\n### Video Tutorials\n- [Hosting MkDocs on Cloudflare Pages](https://www.youtube.com/watch?v=7-HhLascLuM) - Techdox\n\n### Plex OAuth Docs (For Developers)\n- [Authenticating with Plex](https://forums.plex.tv/t/authenticating-with-plex/609370)\n- [Security alert when authenticating with Plex](https://forums.plex.tv/t/security-alert-when-authenticating-with-plex/887330)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistercalvin%2Fmkdocs-plex-guide-template-cf-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistercalvin%2Fmkdocs-plex-guide-template-cf-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistercalvin%2Fmkdocs-plex-guide-template-cf-pages/lists"}