Josh: Updated documentation from markdown files

2026-05-16T14:04:36Z

Updated documentation from markdown files

← Older revision		Revision as of 14:04, 16 May 2026
Line 245:		Line 245:

	<pre class="lang-bash">		<pre class="lang-bash">
	WIKI_URL="~~http~~://10.8.~~0.2:8080~~"		WIKI_URL="https://wiki.jb-vpn.uk"
	USERNAME="your_username"		USERNAME="your_username"
	PASSWORD="your_password"		PASSWORD="your_password"
Line 303:		Line 303:
	<pre class="lang-bash">		<pre class="lang-bash">
	==== Test connectivity ====		==== Test connectivity ====
	~~curl -I http://10.8.0.2:8080~~
	curl -I https://wiki.jb-vpn.uk		curl -I https://wiki.jb-vpn.uk

	== Test API ==		== Test API (public or local) ==
	curl "http://10.8.0.2:~~8080~~/api.php?action=query&meta=siteinfo&format=json"		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>		</pre>

Josh: Major update - troubleshooting guide: Uploading Documentation to Wiki (61 sections) (wiki management)

2026-01-01T13:44:59Z

Major update - troubleshooting guide: Uploading Documentation to Wiki (61 sections) (wiki management)

Show changes

Josh: Minor update - troubleshooting guide: Uploading Documentation to Wiki (24 sections) (wiki management)

2026-01-01T13:28:41Z

Minor update - troubleshooting guide: Uploading Documentation to Wiki (24 sections) (wiki management)

Show changes

Josh: Added troubleshooting guide: Uploading Documentation to Wiki (wiki management)

2026-01-01T13:16:23Z

Added troubleshooting guide: Uploading Documentation to Wiki (wiki management)

New page

= Uploading Documentation to Wiki =

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="http://10.8.0.2:8080"
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 http://10.8.0.2:8080
curl -I https://wiki.jb-vpn.uk

= Test API =
curl "http://10.8.0.2:8080/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]]

Wiki Management:Upload Instructions - Revision history

Josh: Updated documentation from markdown files

Josh: Major update - troubleshooting guide: Uploading Documentation to Wiki (61 sections) (wiki management)

Josh: Minor update - troubleshooting guide: Uploading Documentation to Wiki (24 sections) (wiki management)

Josh: Added troubleshooting guide: Uploading Documentation to Wiki (wiki management)