MediaWiki

Extension:PageSync

MediaWiki extensions manual
PageSync
Release status: stable
Implementation Parser extension , API
Description Export and import wiki pages
Author(s) Charlot Cobben (Sen-Saitalk)
Latest version 2.6.5 (19/06/2024)
Compatibility policy For every MediaWiki release that is a Long Term Support release there is a corresponding branch in the extension.
MediaWiki 1.35.+;1.39+
PHP 7+
Composer open-csp/page-sync
License GNU General Public License 2.0 only
Download

GitHub:

Note:
No localisation updates are
provided by translatewiki.net .


Readme
ChangeLog
Parameters
PageSync
Hooks used

The PageSync extension allows storing any wiki page content in a file on the server, allowing it to be pushed to git or Bitbucket and deployed on another server. The rationale for developing PageSync was to have all application artifacts under version control, including templates, forms, and other pages in the wiki.

PageSync has a maintenance script to import pages from files. This enables automatic wiki deployment and content transfer from one wiki to another.

PageSync can sync all Multi Revision Content slots and Files in the File namespace. Additionally, you can save all synced files as a ZIP Archive and exchange the ZIP archive.

Detailed Documentation can be found at the following link: https://www.open-csp.org/DevOps:Doc/PageSync

Installation

edit
  • Download and place the file(s) in a directory called PageSync in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file: 
    $wgPageSync['filePath']=</path/to/stored-synced-files>
$wgPageSync['tempFilePath']=</path/to/temporary-directory>
wfLoadExtension( 'PageSync' );
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Or install using Composer. Read more here: https://www.mediawiki.org/wiki/Composer/For_extensions

The Composer required name is: open-csp/page-sync

Configuration

edit

PageSync needs a full path to a directory to store the files that can be synced, e.g., $IP/psFiles

This can be set in the "LocalSettings.php" file as: 

$wgPageSync['filePath'] =  $IP . '/psFiles';

PageSync also needs a temporary file path to a directory to handle received Share files. 

$wgPageSync['tempFilePath'] =  $IP . '/wspsTemp';

$wgallowedGroups is a configuration parameter that tells PageSync what user groups can add pages to be synced. It defaults to sysop. 

$wgPageSync['allowedGroups'] = [ "sysop" ];

Make sure these maps have the correct rights for PageSync to store files.

It is also a good practice to store these files outside your HTML folder. The content of pages is stored as raw wikitext, and although you can store synced files in subfolders hidden within the root, they are potentially visible.

Files from the File namespace will also be synced.

You can define what slots you want to sync. The default value is all. If you change this value, add "main" for the main content slot. 

$wgPageSync['contentSlotsToBeSynced'] = "all";

or 

$wgPageSync['contentSlotsToBeSynced'] = ['main', 'my-content-slot'];

Usage

edit

See also the Special page section below.

If you are a sysop, any page that can be synced will have a slider in the top menu. Click on it, and it will turn blue, indicating that it was synced (a notification will also be shown). If the slider is already blue when you visit a page, it simply means the page is already synced and is being monitored for changes. Click the slider again to exclude the page from syncing.

User rights

edit

sysop/admins are allowed to set a page to be synced. All other users have no such ability.

Special Page

edit

By default, the special page lists all Wiki pages set for syncing.

You can also create, restore, and delete ZIP backups from the special page. To use ZIP Backups, make sure ZIPArchive is installed on your PHP setup.

The special page also allows you to do a Semantic MediaWiki Query to add certain pages to PageSync quickly. This feature only works if you have the SemanticMediaWiki extension installed.

The Special Page also shows all currently synced pages.

Creating PageSync Share files is also done from the Special page.

Finally, you can delete all synced pages from the Special page. This will not delete any pages in the Wiki, only the ones stored on the server by PageSync.

Update to version 0.9.9.9+

edit

Since the file structure has changed as of version 0.9.9.9 to support Content Slots, upgrading requires some extra effort. We have tried to make this very effortlessly. Once you have installed the 0.9.9.9+ update, visit the Wiki. You will notice that the sync button in the admin menu has an exclamation mark. Clicking this will bring you to a special page. Make sure you do not sync any pages to avoid possible failures. The first thing you should do is use the new feature to create a backup. This will bring you to the backup tab, where you can find your new backup file. Click on the PageSync logo to return to the converted page. Now click convert files preview. This will give you an overview of the affected files. Click on convert files to convert all the synced files to version 0.9.9.9.

Maintenance script

edit

A maintenance script can be run to import previously exported pages.

Options

edit
summary
Additional text will be added to the files imported History.
user
Your username. It will be added to the import log. [mandatory]
rebuild-index
Rebuild the index file from existing files in the export folder
force-rebuild-index
Used with 'rebuild-index' to suppress confirmation
rebuild-files
Will take the index file and re-create all files from the database
force-rebuild-files
Used with rebuild-files. These forces rebuild-files without prompting for user interaction

ShareFile import options

install-shared-file
Url or path on the server to a PageSync share file
install-shared-file-from-temp
Name of the PageSync Share file already in the PageSync TempPath
silent
Will show no output in the terminal until it is finished.

Example

edit 
SERVER_NAME=<myservername> php extensions/PageSync/maintenance/WSps.maintenance.php --user 'Maintenance script' --summary 'Fill database'

Scenario

edit

We usually have a developing environment. When development is done, we push our code to a repository. From there, we create a Docker container and deploy it to a Testing server. From there, it is deployed to an Acceptance server and production.

This is all fine with PHP or JavaScript code, but we also create templates and widgets that are fundamental for everything to work correctly.

With PageSync, we can now push our Templates, Widgets, or any important Wiki page to our repository. When deploying a container, the PageSync maintenance script automatically updates wiki pages.

Version 2.0.0 has a major change in its file management. Read the installation manual before installing this version, as it is incompatible with previous versions. (https://www.open-csp.org/DevOps:Doc/PageSync/2.0/Installing_PageSync)

Version history

edit
Version 2.6.5
The maintenance script rebuild-index is now, by default, verbose. Added function to add pages NS and title search. i18n changes
Version 2.6.3
Version bump only due to a change in 1.39 branch
Version 2.6.2
Composer update to reflect the Open CSP package
Version 2.6.1
Added support for installing PageSync Shared files uploaded to the wiki.
Version 2.5.0
Added administrative function to manage tags and synced pages. Real-time search on the index page.
Version 2.1.5
REL1_39 compatibility update. REL1_35 and maintenance-only version bump
Version 2.1.4
Content-aware slots added
Version 2.1.3

Maintenance script color difference between success and skipped

Version 2.1.2
Add before pagedisplay hook back in
Version 2.1.1
Fixed bug when the synced page was altered
Version 2.1.0
Add Installing Shared file from PageSync Repo. Rewrote the code partly.
Version 2.0.10
Fixed installing Shared file bug
Version 2.0.9
Extra Share file checks were added, and non-valid URL warnings cached
Version 2.0.8
Separated config from main
Version 2.0.6
Removed PHP notice and newline ( Gitlab #13 )
Version 2.0.5
Added maintenance option rebuild-files to rebuild all files from the index.
Version 2.0.4
Fixed bug in Shared file import
Version 2.0.3
Added onArticleDelete hook ( this is deprecated, but we only support LTS versions of MW )
Version 2.0.2
Fixed title look-up in conversion to version 2
Version 2.0.0
New file management system to fix a problem with multi-language wikis
Version 1.5.2
Added overview installing shared file through Maintenance script
Version 1.5.1
Made maintenance option silent more silent. Added special option.
Version 1.5.0
Sharing Files added. Rename to PageSync.
Version 1.1.0
Rewrote deprecated 1.35.1+ code. Unchanged pages will no longer update synced files on the server
Version 1.0.1

Added support for different content types

Version 1.0
Initial release
Version 1alpha5
Created handlers classes and cleaned the special page. Added requirements.
Version 1alpha4
Added consistency in the maintenance script
Version 1alpha3
fixed on page save
Version 1alpha2
Fixed weird username JavaScript error on one specific wiki
Version 1alpha1
Added support message when files are not in the index. Removed debug information.
Version 0.9.9.9
Removed Maintenance script option --rc, --overwrite, and --timestamp. Added slot support. Added rebuild index option. Added backup and restore.
Version 0.9.9.8

MW code style

Version 0.9.9.7
Sub special pages visual fix for most MW skins
Version 0.9.9.6
We are not using the user received from API anymore. Added a check to show only the sync button if a page can be synced. ( introduced by SkinTemplateNavigation::Universal )
Version 0.9.9.5
Fix for skins other than Chameleon
Version 0.9.9.4
Delete un-used translations
Version 0.9.9.1 - 0.9.9.3
Clean-up
Version 0.9.9
Initial Community release

Discord

edit

Ask any question at the PageSync Discord server: https://discord.gg/T8VTjtXGnV

See also

edit
  • EMWCon Spring 2021  : There was a presentation on WSPageSync. The presentation file can be downloaded. You can also watch the presentation on YouTube.
  • Page import - overview of all page import tools
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:PageSync&oldid=6740013"