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.
External content can be embedded via the #embed
parser function. This function takes a URL.
Markdown and code syntax highlighting are supported. To render markdown, no additional parameters are needed. To use code
syntax highlighting, refer to the parameters below.
Example:
{{#embed:https://example.com/fluffy/kittens.md}}
There is special handling for GitHub URLs, removing the need to provide the raw file URL:
master
branchContent from Bitbucket can be embedded via the #bitbucket
parser function.
This function takes a URL and includes the following Bitbucket-specific behavior:
/browse
URLs are automatically turned into /raw
URLsREADME.md
Example:
{{#bitbucket:https://git.example.com/projects/HI/repos/cats/browse}}
{{#bitbucket:https://git.example.com/projects/HI/repos/cats/raw/README.md?at=refs%2Fheads%2Fmaster}}
Both #embed
and #bitbucket
can be customized with these parameters:
lang
: (Optional) One of the supported languages. Only necessary if the language is not detected from the file extension.lineNumbers
: (Optional) Show line numbers.showLines
: (Optional) Show only specific lines. It can be a single line number or a range separated with a hyphen (-). Multiple line numbers or ranges can be separated by commas.render
: (Optional) render Markdown (this is the default behavior unless $wgExternalContentRenderMarkdownByDefault
is changed)Examples:
Show Markdown file contents in a code block:
{{#embed:https://example.com/fluffy/kittens.md|lang=markdown}}
Show code block with line numbers:
{{#embed:https://example.com/fluffy/kittens.php|lang=php|line}}
Show only specific lines in a code block:
{{#embed:https://example.com/fluffy/kittens.php|lang=php|showLines=1-3,8}}
Render file as Markdown:
{{#embed:https://example.com/fluffy/kittens.php|render}}
To refresh all the pages containing one of the parser functions added by this extension, run
php extensions/ExternalContent/maintenance/RefreshExternalContent.php
Parameters: none
Platform requirements:
The recommended way to install External Content 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:~2.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 wiki's Special:Version page in your browser.
Configuration can be changed via LocalSettings.php.
By default, markdown is rendered rather than shown in a code block.
Variable: $wgExternalContentRenderMarkdownByDefault
Default: true
- markdown is rendered (unless otherwise specified by the user)
Example: false
- markdown is shown as a code block (unless otherwise specified by the user)
List of allowed domains to embed content from. Leave empty to have no restriction.
Variable: $wgExternalContentDomainWhitelist
Default: []
Example: [ 'git.example.com', 'another.example.com' ]
List of allowed file extensions. Leave empty to have no restriction.
Variable: $wgExternalContentFileExtensionWhitelist
Default: []
Example: [ 'md', 'txt' ]
Caution: The extension currently only supports markdown: any retrieved file content will be rendered ask markdown.
If the #embed
parser function should be enabled.
Variable: $wgExternalContentEnableEmbedFunction
Default: true
Example: false
- disables the #embed
parser function
If the #bitbucket
parser function should be enabled.
Variable: $wgExternalContentEnableBitbucketFunction
Default: true
Example: false
- disables the #bitbucket
parser function
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.
The content of files is fetched via MediaWiki's native HTTP client. This process is affected by various HTTP client variables.
In stock MediaWiki with no extensions, embedded content is not searchable. To make embedded content show up in search results, install Elasticseach and the CirrusSearch extension.
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"
]
}
}
}
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 analysisAlternatively, you can execute commands from the MediaWiki root directory:
php tests/phpunit/phpunit.php -c extensions/ExternalContent/
vendor/bin/phpcs -p -s --standard=extensions/ExternalContent/phpcs.xml
vendor/bin/phpstan analyse --configuration=extensions/ExternalContent/phpstan.neon --memory-limit=2G
php vendor/bin/psalm --config=extensions/ExternalContent/psalm.xml
lang
parameterlineNumbers
parametershowLines
parameterrender
parameter#embed
parser functionInitial release for MediaWiki 1.35+ with these features:
#embed
parser function#bitbucket
parser function$wgExternalContentDomainWhitelist
setting$wgExternalContentDomainWhitelist
setting$wgExternalContentBasicAuthCredentials
setting#embed
via the $wgExternalContentEnableEmbedFunction
setting#bitbucket
via the $wgExternalContentEnableBitbucketFunction
settingRefreshExternalContent.php
maintenance scriptPages with external content
categoryPages with broken external content
category