Plex Documentation Guide

A standardized documentation template for your Plex server, built with Material for MkDocs and deployed via GitHub Pages. This template includes pre-built pages covering common Plex topics like streaming quality, content requests, transcoding, and more.

✨ Features

• 📚 Pre-built pages for common Plex topics
• 🔄 Automatic deployment via GitHub Actions
• 🎨 Material for MkDocs theme with custom styling
• 🔧 Easy configuration through environment variables

🚀 Getting Started

Important

Complete all steps below to ensure your site deploys correctly. Missing any step will cause the deployment to fail.

1. Fork this repository to your own GitHub account

2. Enable GitHub Pages:

   • Go to Settings > Pages
   • Under "Build and deployment", change Source to "GitHub Actions"
   • Wait for the blue success message "GitHub Pages source saved"

3. Enable GitHub Actions:

   • Go to Actions tab
   • Click "I understand my workflows, go ahead and enable them"

4. Run the workflow:

   • Option 1: Modify and push a change (e.g., customize variables in main.py)
   • Option 2: Manually trigger the workflow
     • Go to Build and Deploy MkDocs Site in the Actions tab
     • Click "Run workflow" dropdown button
     • Select branch (main) and click "Run workflow"

Your site will be available at https://yourusername.github.io/mkdocs-plex-guide-template after the workflow completes.

The template will automatically use your GitHub username and repository name throughout the site. You can see this in action at my demo site: https://mistercalvin.github.io/mkdocs-plex-guide-template

📝 Customization

Basic Configuration

The following values are automatically set via environment variables in ci.yml and used in the header + footer of your MKDocs site:

• username - Your GitHub username (lowercase)
• repo_name - Repository name
• year - Current year

Required Variables and Default Values

Note

These can also be set in Settings > Security > Secrets and variables > Actions > Variables

The following values can be set in main.py. These values are used throughout the rendered site pages:

• request_url - request.example.com
• plex_url - plex.example.com
• plex_libraries - Movies and TV Shows
• noreply_email - [email protected]

Content Customization

Key files to modify:

• docs/*.md - Documentation pages
• docs/stylesheets/extra.css - Custom admonitions
• docs/assets/ - Images and video

🔧 Troubleshooting

If your deployment fails, check:

1. GitHub Pages is enabled and set to "GitHub Actions" as the source
2. GitHub Actions is enabled for your repository

If you have an older fork and are encountering persistent issues:

Tip

As a last resort (if you don't have many custom changes), you can try deleting and re-forking the repository. This template is actively maintained in the main branch since GitHub Pages currently doesn't support multiple branch deployments. While this feature is planned, for now all development happens in the main branch, which might occasionally lead to breaking changes.

📚 Resources

Documentation / Plugins

• Material for MkDocs - Getting started
• MkDocs Plugins Catalog
• MKDocs Password Encryption Plugin

Video Tutorials

• Creating Documentation with MkDocs Material Theme - James Willett
• Hosting MkDocs on Cloudflare Pages - Techdox