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
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:
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 everythingmake test
: Run all testsmake 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