mkdocs-sharepoint-plugin 1.2.0

MkDocs plugin to publish documentation to SharePoint

MkDocs SharePoint Plugin

A MkDocs plugin that automatically publishes your built documentation site to SharePoint Online.

Features

• Automatic publishing - Upload the MkDocs site_dir output to SharePoint during mkdocs build
• Folder structure preservation - Maintains subdirectories when uploading to a document library
• App-based authentication - Uses Microsoft Entra app credentials (client ID/secret)
• Flexible configuration - Config values with environment variable fallbacks
• Dry-run mode - Test your configuration without publishing
• Debug mode - Detailed logging for troubleshooting
• Retry support - Exponential backoff for transient SharePoint API failures

Installation

Install from Source

pip install .

Development Installation

pip install -e ".[dev]"

Build from Source

python -m build
pip install dist/mkdocs_sharepoint_plugin-*.whl

Python Requirements

• Python: >=3.7
• Build System: setuptools>=61, wheel, build

Dependencies

Core Dependencies

• mkdocs - The static site generator this plugin extends
• Office365-REST-Python-Client - SharePoint REST API client
• tenacity - Retry/backoff for API calls
• requests - HTTP library
• pyyaml - YAML parsing

Configuration

The plugin is registered as a MkDocs plugin via the entry point:

sharepoint = "mkdocs_sharepoint_plugin.plugin:SharePointPlugin"

Add the plugin to your mkdocs.yml:

plugins:
  - sharepoint:
      site_url: https://contoso.sharepoint.com/sites/Team
      tenant_id: your-tenant-id
      documents_folder: /sites/Team/Shared Documents/Docs
      upload_api: graph
      enabled_if_env: MKDOCS_TO_SHAREPOINT
      dryrun: false
      debug: false

Configuration Options

Option	Description	Default	Required
site_url	SharePoint site URL	$SHAREPOINT_SITE_URL	✅
client_id	Entra app client ID	$SHAREPOINT_CLIENT_ID	✅
client_secret	Entra app client secret	$SHAREPOINT_CLIENT_SECRET	✅
tenant_id	Entra tenant ID	$SHAREPOINT_TENANT_ID / $AZURE_TENANT_ID	✅ for Graph
documents_folder	Server-relative document library folder		✅
pages_folder	Server-relative Site Pages folder (for wiki helpers)	null
upload_api	Upload API: graph or rest	graph
enabled_if_env	Environment variable to enable plugin
dryrun	Test mode without publishing	false
debug	Enable debug logging	false

Usage

Basic Usage

1. Configure the plugin in your mkdocs.yml
2. Set up environment variables for SharePoint authentication:

   export SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/Team
   export SHAREPOINT_CLIENT_ID=your-client-id
   export SHAREPOINT_CLIENT_SECRET=your-client-secret
   export SHAREPOINT_TENANT_ID=your-tenant-id
   export MKDOCS_TO_SHAREPOINT=1
   

3. Build and publish your documentation:

   mkdocs build
   

When enabled_if_env is set, the plugin only publishes when the environment variable equals 1.

Dry Run

Set dryrun: true in your plugin config to log what would be uploaded without calling the SharePoint API.

SharePoint API Helpers

The repo also includes helper functions and an optional CLI for direct SharePoint publishing outside MkDocs:

• Module: src/mkdocs_sharepoint_plugin/sharepoint_publish.py
• CLI: tools/sharepoint_publish.py

Example CLI usage:

python tools/sharepoint_publish.py upload-docs \
    --local-dir site \
    --server-folder "/sites/your-site/Shared Documents/Docs" \
    --upload-api graph

python tools/sharepoint_publish.py create-wiki \
    --title "How do I reset my password?" \
    --html-file page.html \
    --pages-folder "/sites/your-site/SitePages"

Development

Run Tests

coverage run -m pytest
coverage report

Format Code

black src tests

Authentication Notes

SharePoint Online automation typically uses app-only authentication in Microsoft Entra ID. The app needs appropriate SharePoint permissions (for example Sites.ReadWrite.All) and admin consent for the tenant.

Store secrets in environment variables or a secrets manager. Do not commit credentials to source control.

Related Projects

• python-mkdocs-to-confluence - Sister plugin for publishing MkDocs documentation to Confluence

Docker Image

Releases publish a versioned container image to GitHub Container Registry via @codedependant/semantic-release-docker:

ghcr.io/polarpoint-io/python-mkdocs-to-sharepoint:<version>

Example usage:

docker run --rm -v "$PWD:/docs" -w /docs \
  ghcr.io/polarpoint-io/python-mkdocs-to-sharepoint:latest build

Tags follow semantic versioning (latest, 1.2.3, 1-latest, 1.2).