Wiki Management:Upload Instructions

This guide explains how to upload the documentation files to your MediaWiki instance.

Option 1: Automated Upload (Recommended)

Use the unified wiki manager script to automatically upload all documentation files.

Prerequisites

The script requires mwclient library, which should already be installed:

pip3 install --break-system-packages mwclient

Usage

First time setup - Store credentials:

python3 /root/wiki_manager.py --store-credentials

Upload all documentation files:

python3 /root/wiki_manager.py --upload

Update the Main Page with documentation links:

python3 /root/wiki_manager.py --update-main-page

Do both at once:

python3 /root/wiki_manager.py --upload --update-main-page

Check sync status:

python3 /root/wiki_manager.py --status

Sync changes from wiki to local files:

python3 /root/wiki_manager.py --sync

Delete orphaned wiki pages (pages that no longer have corresponding local files):

== Preview what would be deleted (dry run - recommended first) ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== Actually delete orphaned pages (with confirmation) ==
python3 /root/wiki_manager.py --delete-orphaned

== Delete orphaned pages without confirmation (non-interactive) ==
python3 /root/wiki_manager.py --delete-orphaned -y

Upload new docs and delete old orphaned pages in one go:

python3 /root/wiki_manager.py --upload --delete-orphaned -y

Managing Orphaned Pages

When you restructure documentation (e.g., breaking large files into smaller sub-pages), old wiki pages may become "orphaned" - they exist on the wiki but no longer have corresponding local files.

The --delete-orphaned feature helps you clean up these old pages:

Safety features:

  * Use --dry-run first to preview what would be deleted

  * Requires confirmation (or use -y flag for non-interactive mode)

  * Shows detailed information about each page before deletion

Example workflow after restructuring documentation:

== 1. First, preview what would be deleted ==
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. If the list looks correct, actually delete them ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload the new restructured documentation ==
python3 /root/wiki_manager.py --upload --update-main-page

Note: The script only deletes pages in the Documentation: namespace that don't have corresponding local files. It will never delete pages that still have local files, ensuring your active documentation is always preserved.

Customizing Upload Comments

By default, the script uses the comment "Uploaded documentation from markdown files" for all uploads. You can customize this behavior in two ways:

Option 1: Custom Comment

Use the --comment flag to specify a custom comment that will be used for all uploads:

python3 /root/wiki_manager.py --upload --comment "Updated documentation for v2.0"

This is useful when you want to provide a specific message for a batch of uploads, such as:

• Version updates: --comment "Documentation update for version 2.1"

• Feature additions: --comment "Added new SSH port forwarding documentation"

• Bug fixes: --comment "Fixed formatting issues in configuration guides"

Option 2: Auto-Generated Comments

Use the --auto-comment flag to automatically generate meaningful comments based on the content of each file:

python3 /root/wiki_manager.py --upload --auto-comment

The auto-comment feature analyzes each file to generate contextual comments such as:

• "Added configuration guide: SSH Port Forwarding (configuration)"

• "Major update - troubleshooting guide: Port Forwarding Troubleshooting (3 sections) (troubleshooting)"

• "Content added - overview: System Overview (getting started)"

The auto-comment generator:

• Detects document type (troubleshooting guide, configuration guide, overview, etc.)

• Identifies whether it's a new page or an update

• Compares with existing wiki content to detect changes (major update, content added, minor update)

• Extracts the document title from markdown headers

• Counts sections to provide context

• Categorizes based on file path

Note: The --comment flag takes precedence over --auto-comment. If both are specified, the custom comment will be used.

Examples:

== Upload with auto-generated comments ==
python3 /root/wiki_manager.py --upload --auto-comment

== Upload with custom comment and update main page ==
python3 /root/wiki_manager.py --upload --update-main-page --comment "Major documentation update"

== Upload with custom comment in non-interactive mode ==
python3 /root/wiki_manager.py --upload --comment "Quick fix" -y

What the Script Does

The unified wiki manager script:

Maps files to wiki pages based on folder structure:

  * getting-started/*.md → Documentation:Page_Name (e.g., getting-started/system-overview/index.md → Documentation:Index)

  * configuration/*.md → Documentation:Page_Name (e.g., configuration/adding-services/step-by-step.md → Documentation:Step By Step)

  * troubleshooting/*.md → Documentation:Page_Name (e.g., troubleshooting/port-forwarding-troubleshooting.md → Documentation:Port Forwarding Troubleshooting)

  * wiki-management/*.md → Documentation:Page_Name (e.g., wiki-management/upload-instructions.md → Documentation:Upload Instructions)

Can identify and delete orphaned wiki pages (pages without corresponding local files)

Customizing Wiki URL

The script automatically detects the wiki URL. To specify a custom URL, edit the script or use environment variables.

---

Option 2: Manual Upload

If you prefer to upload manually or the script doesn't work:

Or navigate directly: https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit

Step 3: Convert and Paste Content

For each documentation file:

Read the markdown file:

   cat /root/documentation/index.md

Manually convert key elements:

  * # Header → = Header =

  * ## Header → == Header ==

  * ### Header → === Header ===

  * Inline code: ` code  → code

  * bold → bold

  * *italic* → *italic*

  * Code blocks: Wrap with <syntaxhighlight lang="bash"> and </syntaxhighlight>

Create the pages:

  * Documentation:Index (from documentation/index.md)

  * Documentation:System_Overview (from documentation/getting-started/system-overview.md)

  * Documentation:Adding_Services (from documentation/configuration/adding-services.md)

  * Documentation:Current_Services (from documentation/configuration/current-services.md)

Step 4: Add Navigation

Create a navigation template or update the main page to link to:

• [Documentation Index](index.md)

• [System Overview](System_Overview.md)

• [Adding Services](Adding_Services.md)

• [Current Services](Current_Services.md)

---

Option 3: Using MediaWiki API with curl

You can also use curl to upload via the MediaWiki API:

Step 1: Get Login Token

WIKI_URL="https://wiki.jb-vpn.uk"
USERNAME="your_username"
PASSWORD="your_password"

==== Get login token ====
LOGIN_TOKEN=$(curl -s "$WIKI_URL/api.php?action=query&meta=tokens&type=login&format=json" | grep -oP '(?<="logintoken":")[^"]''' # Login
LOGIN_RESULT=$(curl -s -c cookies.txt -b cookies.txt \
  -d "action=login" \
  -d "lgname=$USERNAME" \
  -d "lgpassword=$PASSWORD" \
  -d "lgtoken=$LOGIN_TOKEN" \
  -d "format=json" \
  "$WIKI_URL/api.php")

echo "Login: $LOGIN_RESULT"

Step 2: Get Edit Token

EDIT_TOKEN=$(curl -s -b cookies.txt \
  "$WIKI_URL/api.php?action=query&meta=tokens&format=json" | \
  grep -oP '(?<="csrftoken":")[^"])''')

Step 3: Upload Page

PAGE_NAME="Documentation:Index"
CONTENT=$(cat /root/documentation/index.md | sed 's/#/=/g')  # Basic conversion

curl -s -b cookies.txt \
  -d "action=edit" \
  -d "title=$PAGE_NAME" \
  -d "text=$CONTENT" \
  -d "token=$EDIT_TOKEN" \
  -d "format=json" \
  "$WIKI_URL/api.php"

Note: This method requires manual markdown-to-wikitext conversion and is more complex.

---

Troubleshooting

Script Authentication Issues

If login fails:

Verify your MediaWiki username and password

Check that your account has edit permissions

Ensure the wiki is accessible from the VPS

Connection Issues

If you can't connect:

==== Test connectivity ====
curl -I https://wiki.jb-vpn.uk

== Test API (public or local) ==
curl "https://wiki.jb-vpn.uk/api.php?action=query&meta=siteinfo&format=json"
curl "http://127.0.0.1:8010/api.php?action=query&meta=siteinfo&format=json"

Permission Issues

Ensure your MediaWiki account has:

• edit permission

• createpage` permission (if pages don't exist)

---

Updating the Main Page

To update the Main Page with links to all documentation:

python3 /root/wiki_manager.py --update-main-page

This will add a comprehensive list of all documentation pages to the Main Page.

Complete Workflow Example

Here's a complete example workflow for restructuring documentation:

==== 1. Preview orphaned pages that would be deleted ====
python3 /root/wiki_manager.py --delete-orphaned --dry-run

== 2. Delete orphaned pages (if the preview looks correct) ==
python3 /root/wiki_manager.py --delete-orphaned -y

== 3. Upload all new/updated documentation ==
python3 /root/wiki_manager.py --upload --auto-comment

== 4. Update the Main Page with new documentation structure ==
python3 /root/wiki_manager.py --update-main-page

== Or do steps 3 and 4 together: ==
python3 /root/wiki_manager.py --upload --update-main-page --auto-comment

---