External Content

MediaWiki extension that allows embedding external content, specified by URL, into your wiki pages.

External Content has been created and is maintained by Professional.Wiki.

• Usage
• Installation
• Configuration
• Development
• Release notes

Usage

Embedding external content

External content can be embedded via the #embed parser function. This function takes a URL. Currently only markdown is supported.

Example:

{{#embed:https://example.com/fluffy/kittens.md}}

Embedding Bitbucket content

Content from Bitbucket can be embedded via the #bitbucket parser function.

This function takes a URL and includes the following Bitbucket specific behavior:

• Validation that the URL matches has the Bitbucket repository structure
• /browse URLs are automatically turned into /raw URLs
• Pointing to the repository root will automatically retrieve README.md

Example:

{{#bitbucket:https://git.example.com/projects/HI/repos/kittens/browse}}
{{#bitbucket:https://git.example.com/projects/HI/repos/kittens/raw/README.md?at=refs%2Fheads%2Fmaster}}

RefreshExternalContent.php script

To refresh all the pages containing one of the parser functions added by this extension, run

php extensions/ExternalContent/maintenance/RefreshExternalContent.php

Parameters: none

Installation

Platform requirements:

• PHP 7.4 or later
• MediaWiki 1.35 or later

The recommended way to install Wikibase EDTF is using Composer with MediaWiki's built-in support for Composer.

On the commandline, go to your wikis root directory. Then run these two commands:

COMPOSER=composer.local.json composer require --no-update professional-wiki/external-content:~1.0
composer update professional-wiki/external-content --no-dev -o

Then enable the extension by adding the following to the bottom of your wikis LocalSettings.php file:

wfLoadExtension( 'ExternalContent' );

You can verify the extension was enabled successfully by opening your wikis Special:Version page in your browser.

Configuration

Configuration can be changed via LocalSettings.php.

Domain whitelist

List of allowed domains to embed content from. Leave empty to have no restriction.

Variable: $wgExternalContentDomainWhitelist

Default: []

Example: [ 'git.example.com', 'another.example.com' ]

File extension whitelist

List of allowed file extensions. Leave empty to have no restriction.

Variable: $wgExternalContentFileExtensionWhitelist

Default: [ 'md' ]

Example: [ 'md', 'txt' ]

Caution: The extension currently only supports markdown: any retrieved file content will be rendered ask markdown.

Enable embed function

If the #embed parser function should be enabled.

Variable: $wgExternalContentEnableEmbedFunction

Default: true

Example: false - disables the #embed parser function

Enable bitbucket function

If the #bitbucket parser function should be enabled.

Variable: $wgExternalContentEnableBitbucketFunction

Default: true

Example: false - disables the #bitbucket parser function

Basic Auth credentials

Per-domain Basic Auth credentials.

Variable: $wgExternalContentBasicAuthCredentials

Default: []

Example:

$wgExternalContentBasicAuthCredentials = [
	'git.example.com' => [ 'ExampleUser', 'ExamplePassword' ],
	'another.example.com' => [ getenv( 'BITBUCKET_USER' ), getenv( 'BITBUCKET_PASSWORD' ) ]
];

The above example shows how you can get credentials from ENV vars, which might be preferred over storing them as plaintext in LocalSettings.php.

Development

To ensure the dev dependencies get installed, have this in your composer.local.json:

{
	"require": {
		"vimeo/psalm": "^4.10",
		"phpstan/phpstan": "^0.12.99"
	},
	"extra": {
		"merge-plugin": {
			"include": [
				"extensions/ExternalContent/composer.json"
			]
		}
	}
}

Running tests and CI checks

You can use the Makefile by running make commands in the ExternalContent directory.

• make ci: Run everything
• make test: Run all tests
• make cs: Run all style checks and static analysis

Alternatively, you can execute commands from the MediaWiki root directory:

• PHPUnit: php tests/phpunit/phpunit.php -c extensions/ExternalContent/
• Style checks: vendor/bin/phpcs -p -s --standard=extensions/ExternalContent/phpcs.xml
• PHPStan: vendor/bin/phpstan analyse --configuration=extensions/ExternalContent/phpstan.neon --memory-limit=2G
• Psalm: php vendor/bin/psalm --config=extensions/ExternalContent/psalm.xml

Release notes

Version 1.0.0 - 2021-09-30

Initial release for MediaWiki 1.35+ with these features:

• Embedding of markdown files via #embed parser function
• Special support for Bitbucket URLs via the #bitbucket parser function
• Restricting of source domains via the $wgExternalContentDomainWhitelist setting
• Restricting of file extensions via the $wgExternalContentDomainWhitelist setting
• Support for Basic Auth via the $wgExternalContentBasicAuthCredentials setting
• Ability to turn off #embed via the $wgExternalContentEnableEmbedFunction setting
• Ability to turn off #bitbucket via the $wgExternalContentEnableBitbucketFunction setting
• Ability to refresh all embedded content via the RefreshExternalContent.php maintenance script
• Ability to view pages with embedded content via the Pages with external content category
• Ability to view pages with broken embedded content via the Pages with broken external content category