Editing 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 <code>mwclient</code> library, which should already be installed:
<pre class="lang-bash">
pip3 install --break-system-packages mwclient
</pre>

=== Usage ===

'''First time setup''' - Store credentials:
<pre class="lang-bash">
python3 /root/wiki_manager.py --store-credentials
</pre>

'''Upload all documentation files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload
</pre>

'''Update the Main Page with documentation links:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

'''Do both at once:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --update-main-page
</pre>

'''Check sync status:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --status
</pre>

'''Sync changes from wiki to local files:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --sync
</pre>

'''Delete orphaned wiki pages''' (pages that no longer have corresponding local files):
<pre class="lang-bash">
== 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
</pre>

'''Upload new docs and delete old orphaned pages in one go:'''
<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --delete-orphaned -y
</pre>

=== 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 <code>--delete-orphaned</code> feature helps you clean up these old pages:

==== '''Finds orphaned pages''': Automatically searches for all <code>Documentation:</code> pages on the wiki and compares them with your local files ====
== '''Shows what would be deleted''': Lists all orphaned pages with their content length ==
== '''Safety features''': ==
   * Use <code>--dry-run</code> first to preview what would be deleted

   * Requires confirmation (or use <code>-y</code> flag for non-interactive mode)

   * Shows detailed information about each page before deletion

'''Example workflow after restructuring documentation:'''

<pre class="lang-bash">
== 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
</pre>

'''Note''': The script only deletes pages in the <code>Documentation:</code> 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 <code>--comment</code> flag to specify a custom comment that will be used for all uploads:

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --comment "Updated documentation for v2.0"
</pre>

This is useful when you want to provide a specific message for a batch of uploads, such as:
* Version updates: <code>--comment "Documentation update for version 2.1"</code>

* Feature additions: <code>--comment "Added new SSH port forwarding documentation"</code>

* Bug fixes: <code>--comment "Fixed formatting issues in configuration guides"</code>

==== Option 2: Auto-Generated Comments ====

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

<pre class="lang-bash">
python3 /root/wiki_manager.py --upload --auto-comment
</pre>

The auto-comment feature analyzes each file to generate contextual comments such as:
* <code>"Added configuration guide: SSH Port Forwarding (configuration)"</code>

* <code>"Major update - troubleshooting guide: Port Forwarding Troubleshooting (3 sections) (troubleshooting)"</code>

* <code>"Content added - overview: System Overview (getting started)"</code>

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 <code>--comment</code> flag takes precedence over <code>--auto-comment</code>. If both are specified, the custom comment will be used.

'''Examples:'''

<pre class="lang-bash">
== 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
</pre>

=== What the Script Does ===

The unified wiki manager script:
==== Automatically discovers all documentation files in the <code>/root/documentation/</code> directory ====
== Converts markdown files to MediaWiki wikitext format ==
== Maps files to wiki pages based on folder structure: ==
   * <code>getting-started/*.md</code> → <code>Documentation:Page_Name</code> (e.g., <code>getting-started/system-overview/index.md</code> → <code>Documentation:Index</code>)

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

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

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

== Uploads all documentation pages to the wiki ==
== Can update the Main Page with links to all documentation ==
== 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:

=== Step 1: Access the Wiki ===

==== Navigate to your wiki: [https://wiki.jb-vpn.uk/index.php?title=Main_Page https://wiki.jb-vpn.uk/index.php?title=Main_Page] ====
== Log in with your MediaWiki account ==

=== Step 2: Create the Documentation Namespace ===

==== Go to: [https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage https://wiki.jb-vpn.uk/index.php?title=Special:CreatePage] ====
== Create a page named <code>Documentation:Index</code> ==
== Or navigate directly: [https://wiki.jb-vpn.uk/index.php?title=Documentation:Index&action=edit 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''': ====
   <pre class="lang-bash">
   cat /root/documentation/index.md
</pre>

== '''Manually convert key elements''': ==
   * <code># Header</code> → <code>= Header =</code>

   * <code>## Header</code> → <code>== Header ==</code>

   * <code>### Header</code> → <code>=== Header ===</code>

   * Inline code: `<code> </code>code<code> </code><code> → </code><code>code</code><code>

   * </code>'''bold'''<code> → </code>'''bold'''<code>

   * </code>*italic*<code> → </code>*italic*<code>

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

== '''Create the pages''': ==
   * </code>Documentation:Index<code> (from </code>documentation/index.md<code>)

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

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

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

=== Step 4: Add Navigation ===

Create a navigation template or update the main page to link to:
* </code>[Documentation Index](index.md)<code>

* </code>[System Overview](System_Overview.md)<code>

* </code>[Adding Services](Adding_Services.md)<code>

* </code>[Current Services](Current_Services.md)<code>

----

== Option 3: Using MediaWiki API with curl ==

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

=== Step 1: Get Login Token ===

<pre class="lang-bash">
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"
</pre>

=== Step 2: Get Edit Token ===

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

=== Step 3: Upload Page ===

<pre class="lang-bash">
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"
</pre>

'''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:
<pre class="lang-bash">
==== 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"
</pre>

=== Permission Issues ===

Ensure your MediaWiki account has:
* </code>edit<code> permission

* </code>createpage` permission (if pages don't exist)

----

=== Updating the Main Page ===

To update the Main Page with links to all documentation:

<pre class="lang-bash">
python3 /root/wiki_manager.py --update-main-page
</pre>

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:

<pre class="lang-bash">
==== 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
</pre>

----

[[Category:Documentation]]
[[Category:Documentation/Wiki Management]]