perxel-wp-guide

A WordPress must-use plugin that renders a branded client handover guide inside the WP admin dashboard. Content is managed via JSON files and screenshot images in a guide/ folder that lives outside the plugin code — pulling plugin updates never overwrites your per-project content.

---

Requirements

• WordPress 6.0+
• PHP 8.0+
• Must be loaded as a mu-plugin (not a regular installable plugin)

---

Installation

Option 1 — Manual

1. Download and unzip this repo
2. Rename the extracted folder to perxel-wp-guide and place it inside wp-content/mu-plugins/
3. Move perxel-wp-guide/perxel-wp-guide-loader.php up one level into wp-content/mu-plugins/

Option 2 — CLI

cd wp-content/mu-plugins

curl -L https://github.com/perxel/perxel-wp-guide/archive/refs/heads/main.tar.gz | tar -xz
mv perxel-wp-guide-main perxel-wp-guide

mv perxel-wp-guide/perxel-wp-guide-loader.php .

Your mu-plugins/ will look like:

mu-plugins/
├── perxel-wp-guide-loader.php
└── perxel-wp-guide/
    ├── perxel-wp-guide.php
    ├── includes/
    ├── assets/
    ├── examples/
    └── guide/

The guide appears in the WP admin sidebar immediately with default config and example content.

---

Updating the plugin

guide/ is never touched — your JSON files and screenshots are safe.

cd wp-content/mu-plugins

find perxel-wp-guide -mindepth 1 -not -path 'perxel-wp-guide/guide*' -delete

curl -L https://github.com/perxel/perxel-wp-guide/archive/refs/heads/main.tar.gz | tar -xz
rsync -a --exclude='perxel-wp-guide-loader.php' perxel-wp-guide-main/. perxel-wp-guide/
rm -rf perxel-wp-guide-main

---

Directory structure

mu-plugins/
├── perxel-wp-guide-loader.php     ← loader (you download once)
└── perxel-wp-guide/               ← this repo
    ├── perxel-wp-guide.php
    ├── includes/
    ├── assets/
    ├── examples/                  ← read-only reference files
    │   └── content/
    │       ├── config.json
    │       ├── 01-dashboard-overview.json
    │       ├── 03-key-areas.json
    │       ├── 04-common-tasks.json
    │       ├── 05-do-not-touch.json
    │       └── 06-support-contact.json
    └── guide/                     ← your project files go here (not in repo)
        ├── content/
        │   ├── config.json
        │   └── 03-key-areas.json  ← copy from examples/content/ and edit
        └── assets/
            ├── project.gif        ← CPT screenshots, named after post type slug
            └── team_member.gif

---

Configuration

Copy examples/content/config.json to guide/content/config.json and fill in your values:

{
  "brand_color": "#1D6FA8",
  "author_name": "Your Agency",
  "client_name": "Client Name",
  "parent_slug": "",
  "menu_title": "Website Guide",
  "menu_slug": "perxel-wp-guide",
  "capability": "edit_posts",
  "hidden": false
}

Key	Default	Description
brand_color	#1D6FA8	Accent color used throughout the guide
author_name	Perxel	Agency name shown in header and footer
client_name	Client	Client name shown on cover page
parent_slug	(empty)	WP admin menu slug to nest under (e.g. tools.php). Empty = top-level menu
menu_title	Website Guide	Label shown in the sidebar
menu_slug	perxel-wp-guide	URL slug: wp-admin/admin.php?page=<slug>. Set this to match an old plugin's slug when migrating
capability	edit_posts	Minimum WP capability required to view the guide
hidden	false	Set to true to remove the guide from the admin entirely

---

Content files

Each section maps to a JSON file in guide/content/. Missing files fall back to the corresponding file in examples/content/ — only create files for sections you want to customize.

File	Section	Falls back to example?
guide/content/config.json	Config	Yes — uses built-in defaults
guide/content/01-dashboard-overview.json	Dashboard overview	Yes
guide/content/03-key-areas.json	Key areas (Site Editor, etc.)	Yes
guide/content/04-common-tasks.json	Common tasks	Yes
guide/content/05-do-not-touch.json	Do not touch	Yes
guide/content/06-support-contact.json	Support & warranty	Yes

Section 02 (Your website content) is auto-generated from registered custom post types — no JSON file needed.

Content formats

01-dashboard-overview.json — WP admin sidebar areas:

[
  {
    "title": "Pages",
    "slug": "pages",
    "path": "edit.php?post_type=page",
    "desc": "Create and manage your static pages."
  }
]

slug is optional — used to match a screenshot image in guide/assets/.

03-key-areas.json — Site Editor templates, settings panels, tools:

[
  {
    "title": "Header template",
    "desc": "Edit the global header shown on every page.",
    "path": "site-editor.php?path=%2Fwp_template",
    "label": "Open in Site Editor"
  }
]

04-common-tasks.json — self-service tasks the client can do:

[
  {
    "title": "Add a new blog post",
    "desc": "Go to Posts → Add New. Fill in the title and body, set a category, then click Publish.",
    "path": "post-new.php",
    "label": "Add new post",
    "img": "post"
  }
]

img is optional — matches a file in guide/assets/ (e.g. guide/assets/post.gif).

05-do-not-touch.json — restricted areas:

[
  {
    "title": "Theme files",
    "desc": "All theme code is version-controlled. Edits outside agreed scope may be identified and billed."
  }
]

06-support-contact.json — warranty and contacts:

{
  "warranty_months": 6,
  "warranty_start": "2025-01-15",
  "contacts": [
    ["Email", "hello@agency.com", "Replies within 1 business day"],
    ["WhatsApp", "+84 900 000 000", "For urgent issues only"]
  ],
  "covered": [
    [true,  "Bug fixes related to the original build"],
    [false, "New features or redesigns (quoted separately)"]
  ]
}

Set warranty_start to "today" to show a placeholder until launch date is confirmed.

---

Screenshots (Section 02)

Drop image files into guide/assets/ named after custom post type slugs:

guide/assets/
├── project.gif
├── team_member.gif
└── service.png

Any registered CPT with a matching image automatically appears in Section 02 with its screenshot. Supported formats: gif, png, jpg, jpeg, webp.

---

Migration from another guide plugin

Set menu_slug in guide/content/config.json to match the old plugin's slug so existing bookmarks keep working:

{
  "menu_slug": "website-guide"
}

---

License

MIT — free to use, fork, and adapt.