{"id":15017747,"url":"https://github.com/professionalwiki/externalcontent","last_synced_at":"2025-04-12T12:32:06.449Z","repository":{"id":40480371,"uuid":"406502036","full_name":"ProfessionalWiki/ExternalContent","owner":"ProfessionalWiki","description":"MediaWiki extension that allows embedding external content","archived":false,"fork":false,"pushed_at":"2025-04-04T20:30:41.000Z","size":779,"stargazers_count":7,"open_issues_count":6,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-04T21:16:56.465Z","etag":null,"topics":["mediawiki","mediawiki-extension"],"latest_commit_sha":null,"homepage":"https://professional.wiki/en/extension/external-content","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ProfessionalWiki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"JeroenDeDauw","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2021-09-14T19:48:40.000Z","updated_at":"2025-04-04T20:30:43.000Z","dependencies_parsed_at":"2023-10-04T00:14:37.461Z","dependency_job_id":"2358ea69-cb6f-44d4-bc99-c86a9dfbaf48","html_url":"https://github.com/ProfessionalWiki/ExternalContent","commit_stats":{"total_commits":154,"total_committers":8,"mean_commits":19.25,"dds":"0.43506493506493504","last_synced_commit":"ae1cfebedf957b3cde6f799e2cc63f545ab390ec"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProfessionalWiki%2FExternalContent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProfessionalWiki%2FExternalContent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProfessionalWiki%2FExternalContent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProfessionalWiki%2FExternalContent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ProfessionalWiki","download_url":"https://codeload.github.com/ProfessionalWiki/ExternalContent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248566579,"owners_count":21125690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mediawiki","mediawiki-extension"],"created_at":"2024-09-24T19:50:56.132Z","updated_at":"2025-04-12T12:32:06.441Z","avatar_url":"https://github.com/ProfessionalWiki.png","language":"PHP","funding_links":["https://github.com/sponsors/JeroenDeDauw"],"categories":[],"sub_categories":[],"readme":"# External Content\n\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ProfessionalWiki/ExternalContent/ci.yml?branch=master)](https://github.com/ProfessionalWiki/ExternalContent/actions?query=workflow%3ACI)\n[![codecov](https://codecov.io/gh/ProfessionalWiki/ExternalContent/branch/master/graph/badge.svg?token=GnOG3FF16Z)](https://codecov.io/gh/ProfessionalWiki/ExternalContent)\n[![Type Coverage](https://shepherd.dev/github/ProfessionalWiki/ExternalContent/coverage.svg)](https://shepherd.dev/github/ProfessionalWiki/ExternalContent)\n[![Psalm level](https://shepherd.dev/github/ProfessionalWiki/ExternalContent/level.svg)](psalm.xml)\n[![Latest Stable Version](https://poser.pugx.org/professional-wiki/external-content/v/stable)](https://packagist.org/packages/professional-wiki/external-content)\n[![Download count](https://poser.pugx.org/professional-wiki/external-content/downloads)](https://packagist.org/packages/professional-wiki/external-content)\n[![License](https://poser.pugx.org/professional-wiki/external-content/license)](LICENSE)\n\n[MediaWiki] extension that allows embedding external content, specified by URL, into your wiki pages.\n\nExternal Content has been created and is maintained by [Professional Wiki].\n\n- [Usage](#usage)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Release notes](#release-notes)\n\n## Usage\n\n\u003ca href=\"https://www.youtube.com/watch?v=U65NhBwnCMU\"\u003e\u003cimg src=\".github/youtube.png\" width=\"430px\" title=\"Play video\" /\u003e\u003c/a\u003e\n\n### Embedding external content\n\nExternal content can be embedded via the `#embed` [parser function]. This function takes a URL.\nMarkdown and code syntax highlighting are supported. No additional parameters are needed to render the markdown. To use code\nsyntax highlighting, refer to the [parameters](#code-syntax-highlighting-parameters) below.\n\nExample:\n\n```\n{{#embed:https://example.com/fluffy/kittens.md}}\n```\n\nThere is special handling for GitHub URLs, removing the need to provide the raw file URL:\n\n* github.com/org/repo/blob/master/hi.md =\u003e raw.githubusercontent.com/org/repo/master/hi.md\n* github.com/org/repo/tree/master/src =\u003e defaults to README.md in the directory\n* github.com/org/repo =\u003e defaults to the README.md in the repository root on the `master` branch\n\n### Embedding Bitbucket content\n\nContent from Bitbucket can be embedded via the `#bitbucket` [parser function].\n\nThis function takes a URL and includes the following Bitbucket-specific behavior:\n* Validation that the URL matches the Bitbucket repository structure\n* `/browse` URLs are automatically turned into `/raw` URLs\n* Pointing to the repository root will automatically retrieve `README.md`\n\nExample:\n\n```\n{{#bitbucket:https://git.example.com/projects/HI/repos/cats/browse}}\n{{#bitbucket:https://git.example.com/projects/HI/repos/cats/raw/README.md?at=refs%2Fheads%2Fmaster}}\n```\n\n### Display parameters\n\nBoth `#embed` and `#bitbucket` can be customized with these parameters:\n\n* `lang`: (Optional) One of the [supported languages]. Only necessary if the language is not detected from the file extension.\n* `lineNumbers`: (Optional) Show line numbers.\n* `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.\n* `render`: (Optional) render Markdown (this is the default behavior unless `$wgExternalContentRenderMarkdownByDefault` is changed)\n\nExamples:\n\nShow Markdown file contents in a code block:\n```\n{{#embed:https://example.com/fluffy/kittens.md|lang=markdown}}\n```\n\nShow code block with line numbers:\n```\n{{#embed:https://example.com/fluffy/kittens.php|lang=php|line}}\n```\n\nShow only specific lines in a code block:\n```\n{{#embed:https://example.com/fluffy/kittens.php|lang=php|showLines=1-3,8}}\n```\n\nRender file as Markdown:\n```\n{{#embed:https://example.com/fluffy/kittens.php|render}}\n```\n\n### Refreshing external content\n\nTo refresh all the pages containing one of the parser functions added by this extension, run\n\n    php extensions/ExternalContent/maintenance/RefreshExternalContent.php\n\nParameters: none\n\n## Installation\n\nPlatform requirements:\n\n* [PHP] 8.0 or later (tested up to 8.3)\n* [MediaWiki] 1.39 or later (tested up to 1.43 and master)\n\nThe recommended way to install External Content is using [Composer] with\n[MediaWiki's built-in support for Composer][Composer install].\n\nOn the commandline, go to your wikis root directory. Then run these two commands:\n\n```shell script\nCOMPOSER=composer.local.json composer require --no-update professional-wiki/external-content:~3.0\n```\n```shell script\ncomposer update professional-wiki/external-content --no-dev -o\n```\n\nThen enable the extension by adding the following to the bottom of your wikis [LocalSettings.php] file:\n\n```php\nwfLoadExtension( 'ExternalContent' );\n```\n\nYou can verify the extension was enabled successfully by opening your wiki's Special:Version page in your browser.\n\n## Configuration\n\nConfiguration can be changed via [LocalSettings.php].\n\n### Rendering markdown\n\nBy default, markdown is rendered rather than shown in a code block.\n\nVariable: `$wgExternalContentRenderMarkdownByDefault`\n\nDefault: `true` - markdown is rendered (unless otherwise specified by the user)\n\nExample: `false` - markdown is shown as a code block (unless otherwise specified by the user)\n\n### Domain whitelist\n\nList of allowed domains to embed content from. Leave empty to have no restriction.\n\nVariable: `$wgExternalContentDomainWhitelist`\n\nDefault: `[]`\n\nExample: `[ 'git.example.com', 'another.example.com' ]`\n\n### File extension whitelist\n\nList of allowed file extensions. Leave empty to have no restriction.\n\nVariable: `$wgExternalContentFileExtensionWhitelist`\n\nDefault: `[]`\n\nExample: `[ 'md', 'txt' ]`\n\nCaution: The extension currently only supports markdown: any retrieved file content will be rendered ask markdown.\n\n### Enable embed function\n\nIf the `#embed` parser function should be enabled.\n\nVariable: `$wgExternalContentEnableEmbedFunction`\n\nDefault: `true`\n\nExample: `false` - disables the `#embed` parser function\n\n### Enable bitbucket function\n\nIf the `#bitbucket` parser function should be enabled.\n\nVariable: `$wgExternalContentEnableBitbucketFunction`\n\nDefault: `true`\n\nExample: `false` - disables the `#bitbucket` parser function\n\n### Basic Auth credentials\n\nPer-domain Basic Auth credentials.\n\nVariable: `$wgExternalContentBasicAuthCredentials`\n\nDefault: `[]`\n\nExample:\n```php\n$wgExternalContentBasicAuthCredentials = [\n\t'git.example.com' =\u003e [ 'ExampleUser', 'ExamplePassword' ],\n\t'another.example.com' =\u003e [ getenv( 'BITBUCKET_USER' ), getenv( 'BITBUCKET_PASSWORD' ) ]\n];\n```\n\nThe above example shows how you can get credentials from ENV vars, which might be preferred over\nstoring them as plaintext in [LocalSettings.php].\n\n### Connection details\n\nThe content of files is fetched via MediaWiki's native HTTP client. This process is affected by\nvarious [HTTP client variables](https://www.mediawiki.org/wiki/Category:HTTP_client_variables).\n\n### Search\n\nIn stock MediaWiki with no extensions, embedded content is not searchable. To make embedded content\nshow up in search results, install Elasticseach and the [CirrusSearch extension].\n\n## Development\n\nTo ensure the dev dependencies get installed, have this in your `composer.local.json`:\n\n```json\n{\n\t\"require\": {\n\t\t\"vimeo/psalm\": \"^4.10\",\n\t\t\"phpstan/phpstan\": \"^0.12.99\"\n\t},\n\t\"extra\": {\n\t\t\"merge-plugin\": {\n\t\t\t\"include\": [\n\t\t\t\t\"extensions/ExternalContent/composer.json\"\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n### Running tests and CI checks\n\nYou can use the `Makefile` by running make commands in the `ExternalContent` directory.\n\n* `make ci`: Run everything\n* `make test`: Run all tests\n* `make cs`: Run all style checks and static analysis\n\nAlternatively, you can execute commands from the MediaWiki root directory:\n\n* PHPUnit: `php tests/phpunit/phpunit.php -c extensions/ExternalContent/`\n* Style checks: `vendor/bin/phpcs -p -s --standard=extensions/ExternalContent/phpcs.xml`\n* PHPStan: `vendor/bin/phpstan analyse --configuration=extensions/ExternalContent/phpstan.neon --memory-limit=2G`\n* Psalm: `php vendor/bin/psalm --config=extensions/ExternalContent/psalm.xml`\n\n## Release notes\n\n### Version 3.0.1 - 2025-04-06\n\n* Fixed compatibility with MediaWiki 1.43 and above (IDatabase TypeError)\n\n### Version 3.0.0 - 2025-04-04\n\n* Raised minimum MediaWiki version from 1.35 to 1.39\n* Added support for MediaWiki 1.40, 1.41, 1.42, and 1.43\n* Translation updates\n\n### Version 2.0.1 - 2023-11-02\n\n* Fixed behavior of the copy button for code blocks with line numbers and/or only specific lines shown\n* Improved display of long lines in code blocks by adding line wrapping\n\n### Version 2.0.0 - 2023-10-30\n\n* Raised minimum PHP version from 7.4 to 8.0\n* Added code syntax highlighting\n    * Added `lang` parameter\n    * Added `lineNumbers` parameter\n    * Added `showLines` parameter\n    * Added `render` parameter\n    * Added copy button to code blocks\n    * Added edit link to Bitbucket code blocks\n\n### Version 1.3.0 - 2022-01-08\n\n* Improved handling of relative links. They now point to the \"browse\" version when embedding using a \"browse\" URL,\n  rather than using the \"raw\" version.\n\n### Version 1.2.0 - 2021-12-02\n\n* Added support for [extended syntax markdown](https://www.markdownguide.org/extended-syntax/)\n\n### Version 1.1.0 - 2021-11-01\n\n* Added normalization for github.com URLs to the `#embed` parser function\n\n### Version 1.0.0 - 2021-09-30\n\nInitial release for MediaWiki 1.35+ with these features:\n\n* Embedding of markdown files via `#embed` parser function\n* Special support for Bitbucket URLs via the` #bitbucket` parser function\n* Restricting of source domains via the `$wgExternalContentDomainWhitelist` setting\n* Restricting of file extensions via the `$wgExternalContentDomainWhitelist` setting\n* Support for Basic Auth via the `$wgExternalContentBasicAuthCredentials` setting\n* Ability to turn off `#embed` via the `$wgExternalContentEnableEmbedFunction` setting\n* Ability to turn off `#bitbucket` via the `$wgExternalContentEnableBitbucketFunction` setting\n* Ability to refresh all embedded content via the `RefreshExternalContent.php` maintenance script\n* Ability to view pages with embedded content via the `Pages with external content` category\n* Ability to view pages with broken embedded content via the `Pages with broken external content` category\n\n[Professional Wiki]: https://professional.wiki/en/mediawiki-development\n[MediaWiki]: https://www.mediawiki.org\n[PHP]: https://www.php.net\n[Composer]: https://getcomposer.org\n[Composer install]: https://professional.wiki/en/articles/installing-mediawiki-extensions-with-composer\n[parser function]: https://www.mediawiki.org/wiki/Help:Magic_words\n[LocalSettings.php]: https://www.mediawiki.org/wiki/Manual:LocalSettings.php\n[CirrusSearch extension]: https://www.mediawiki.org/wiki/Extension:CirrusSearch\n[supported languages]: https://prismjs.com/#supported-languages\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofessionalwiki%2Fexternalcontent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofessionalwiki%2Fexternalcontent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofessionalwiki%2Fexternalcontent/lists"}