External Content

Embedding External Content

External content can be embedded via the #embed parser function. This function takes a URL. Markdown and code syntax highlighting are supported. No additional parameters are needed to render the markdown. To use code syntax highlighting, refer to the display 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:

• github.com/org/repo/blob/master/hi.md => raw.githubusercontent.com/org/repo/master/hi.md
• github.com/org/repo/tree/master/src => defaults to README.md in the directory
• github.com/org/repo => defaults to the README.md in the repository root on the master branch

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 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/cats/browse}}
{{#bitbucket:https://git.example.com/projects/HI/repos/cats/raw/README.md?at=refs%2Fheads%2Fmaster}}

Display Parameters

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|lineNumbers}}

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}}

Refreshing External Content

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

php extensions/ExternalContent/maintenance/RefreshExternalContent.php

Parameters: none

Configuration can be changed via LocalSettings.php.

Rendering Markdown

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)

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: []

Example: [ 'md', 'txt' ]

Caution: The extension currently only supports markdown: any retrieved file content will be rendered as 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.

Connection Details

The content of files is fetched via MediaWiki's native HTTP client. This process is affected by various HTTP client variables.

Search

In stock MediaWiki with no extensions, embedded content is not searchable. To make embedded content show up in search results, install Elasticsearch and the CirrusSearch extension.