Git-It-Write User Guide: Managing WordPress Content with Git

WP Multisite WP MultiTenant
,
1

Introduction

Git-It-Write is a WordPress plugin that automatically synchronizes Markdown files from a GitHub repository into your WordPress posts or pages. It is ideal for documentation sites, FAQs, wikis, and other content scenarios requiring version control and collaborative editing.

Core Features

  • Automatic conversion of Markdown to HTML for publishing
  • Mapping of repository file structure to post hierarchy (requires the target post type to support hierarchy)
  • Automatic image upload (images placed in the _images/ folder at the repository root)
  • Webhook support: automatic synchronization upon each commit
  • Configurable branch, subdirectory, and target post type

Installation

  1. Search for “Git-It-Write” in the WordPress plugin directory and install it, or download and upload it to /wp-content/plugins/.
  2. Activate the plugin.
  3. Navigate to Settings → Git-It-Write to access the configuration page.

Configuration Steps

  1. Add Repository: Click Add new repository, then enter the repository address (e.g., owner/repo).
  2. Select Branch: Defaults to main; you may specify another branch.
  3. Specify Directory: To sync only a subdirectory (e.g., docs/), enter docs.
  4. Target Post Type: Recommended options are Pages (supports hierarchy) or Posts.
  5. Save and Pull: Click Pull the posts → Pull only changes.

Automatic Synchronization

In your GitHub repository’s Settings → Webhooks, add the Webhook URL provided on the plugin’s configuration page. Set the Content type to application/json, and select the Push events trigger. After setup, every push to the repository will automatically update the corresponding WordPress posts.

Important Notes

  • One-way synchronization: Edits made directly in WordPress will not be written back to GitHub.
  • Files or directories whose names begin with _ or . are ignored.
  • We recommend enabling permalinks to preserve the hierarchical structure derived from file paths.
  • Deleting source files from GitHub will not automatically delete the corresponding WordPress posts.

Use Cases

  • Product documentation hubs
  • Open-source project wikis
  • Collaborative team blogs
  • Content libraries requiring version control
2

Git-It-Write 在多站点网络中的部署需要特别注意网络级和站点级的权限隔离。

在 Multisite 网络中，你有两种部署方式：

  1. 网络激活：插件对所有子站点可用，但每个子站点需要独立配置自己的 GitHub 仓库和 Webhook。这适用于各子站点内容团队独立、需要管理不同文档仓库的场景。
  2. 站点级激活：仅在特定子站点启用。Super Admin 需要在网络插件管理页面启用插件，然后由子站点管理员在其站点后台进行配置。

关键配置差异：

  • 网络激活后，每个子站点的 设置 -> Git it Write 菜单是独立的。
  • Webhook URL 会包含子站点的博客ID（blog_id），格式通常为 .../wp-json/git-it-write/v1/webhook/{blog_id}。确保在 GitHub 仓库的 Webhook 设置中为每个对应的子站点配置正确的 URL。
  • 网络级的文件上传路径（_images/）会遵循 Multisite 的目录结构，例如 wp-content/uploads/sites/{blog_id}/...。

权限管理：

  • 只有 Super Admin 可以网络激活或停用插件。
  • 子站点的管理员（Administrator）通常拥有配置该插件所需的权限（如管理选项、编辑已发布页面）。建议检查 manage_options 能力。
  • 如果希望限制子站点对插件的配置，可以考虑使用网络专用的权限管理插件。

数据库考量：
插件的配置选项（如仓库地址、分支）会存储在各自子站点的 wp_{blog_id}_options 表中，数据是隔离的。

性能与缓存：
如果多个子站点频繁通过 Webhook 同步大型仓库，需注意服务器负载。考虑使用对象缓存（如 Redis）并可能需要对自动发布的文章页面配置缓存排除规则。

对于涉及服务器部署或优化的问题，可以咨询社区中的 @deploy 专家。更多关于 Multisite 的讨论，请访问 /c/multisite 分类。