README

允许将指定URL的外部内容嵌入到您的维基页面上的MediaWiki扩展。

外部内容由 Professional Wiki 创建并维护。

• 使用方法
• 安装
• 配置
• 开发
• 发行说明

使用方法

嵌入外部内容

外部内容可以通过#embed 解析函数嵌入。此函数接受一个URL。支持Markdown和代码语法高亮。要渲染Markdown，不需要额外的参数。要使用代码语法高亮，请参考下面的参数。

示例

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

对于GitHub URL，有特殊的处理，不需要提供原始文件URL

• github.com/org/repo/blob/master/hi.md => raw.githubusercontent.com/org/repo/master/hi.md
• github.com/org/repo/tree/master/src => 默认为目录中的README.md
• github.com/org/repo => 默认为主仓库根目录上的README.md文件，在master分支

嵌入Bitbucket内容

可以通过#bitbucket 解析函数嵌入Bitbucket内容。

此函数接受一个URL，并包含以下Bitbucket特定行为

• 验证URL是否与Bitbucket仓库结构匹配
• /browse URL会自动转换为/raw URL
• 指向仓库根目录将自动检索README.md

示例

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

显示参数

可以通过以下参数自定义#embed和#bitbucket

• lang: (可选) 支持的语言之一。如果文件扩展名没有检测到语言，则必须指定。
• lineNumbers: (可选) 显示行号。
• showLines: (可选) 只显示特定行。可以是单个行号或由短横线(-)分隔的范围。多个行号或范围可以用逗号分隔。
• render: (可选) 渲染Markdown（这是默认行为，除非更改了$wgExternalContentRenderMarkdownByDefault）

示例

在代码块中显示Markdown文件内容

{{#embed:https://example.com/fluffy/kittens.md|lang=markdown}}

显示带行号的代码块

{{#embed:https://example.com/fluffy/kittens.php|lang=php|line}}

在代码块中只显示特定行

{{#embed:https://example.com/fluffy/kittens.php|lang=php|showLines=1-3,8}}

将文件渲染为Markdown

{{#embed:https://example.com/fluffy/kittens.php|render}}

刷新外部内容

要刷新包含此扩展添加的解析函数之一的所有页面，请运行以下命令

php extensions/ExternalContent/maintenance/RefreshExternalContent.php

参数: 无

安装

平台要求

• PHP 8.0或更高版本（已测试到8.1）
• MediaWiki 1.35或更高版本（已测试到1.39和master）

安装外部内容的推荐方法是使用Composer与MediaWiki内置的Composer支持。

在命令行中，进入您的维基根目录。然后运行以下两个命令

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

composer update professional-wiki/external-content --no-dev -o

然后通过将以下内容添加到您的维基百科 LocalSettings.php 文件底部来启用扩展。

wfLoadExtension( 'ExternalContent' );

您可以通过在浏览器中打开您维基百科的 Special:Version 页面来验证扩展是否成功启用。

配置

配置可以通过 LocalSettings.php 进行更改。

渲染 markdown

默认情况下，markdown 以代码块的形式显示，而不是渲染。

变量: $wgExternalContentRenderMarkdownByDefault

默认: true - markdown 被渲染（除非用户另有指定）

示例: false - markdown 以代码块的形式显示（除非用户另有指定）

域名白名单

列出允许嵌入内容的域名。留空则不进行限制。

变量: $wgExternalContentDomainWhitelist

默认: []

示例: [ 'git.example.com', 'another.example.com' ]

文件扩展名白名单

列出允许的文件扩展名。留空则不进行限制。

变量: $wgExternalContentFileExtensionWhitelist

默认: []

示例: [ 'md', 'txt' ]

注意：扩展当前仅支持 markdown：检索到的任何文件内容都将按 markdown 进行渲染。

启用嵌入功能

如果应启用 #embed 解析函数。

变量: $wgExternalContentEnableEmbedFunction

默认: true

示例: false - 禁用 #embed 解析函数

启用 bitbucket 功能

如果应启用 #bitbucket 解析函数。

变量: $wgExternalContentEnableBitbucketFunction

默认: true

示例: false - 禁用 #bitbucket 解析函数

基本认证凭证

按域名的基本认证凭证。

变量: $wgExternalContentBasicAuthCredentials

默认: []

示例

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

上面的示例显示了如何从 ENV 变量中获取凭证，这可能会比在 LocalSettings.php 中以明文形式存储凭证更受欢迎。

连接详情

文件内容通过 MediaWiki 的原生 HTTP 客户端获取。此过程受各种 HTTP 客户端变量 的影响。

搜索

在未安装扩展的标准 MediaWiki 中，嵌入的内容不可搜索。要使嵌入的内容显示在搜索结果中，请安装 Elasticseach 和 CirrusSearch 扩展。

开发

为确保安装了开发依赖项，请将以下内容添加到您的 composer.local.json

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

运行测试和 CI 检查

您可以通过在 ExternalContent 目录中运行 make 命令来使用 Makefile。

• make ci: 运行所有内容
• make test: 运行所有测试
• make cs: 运行所有样式检查和静态分析

或者，您可以从 MediaWiki 根目录执行命令

• PHPUnit: php tests/phpunit/phpunit.php -c extensions/ExternalContent/
• 样式检查: 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

发行说明

版本 2.0.1 - 2023-11-02

• 修复了具有行号和/或仅显示特定行的代码块的复制按钮的行为
• 通过添加换行，改善了代码块中长行的显示

版本 2.0.0 - 2023-10-30

• 将最低 PHP 版本从 7.4 提高到 8.0
• 添加了代码语法高亮显示
  • 添加了 lang 参数
  • 添加了 lineNumbers 参数
  • 添加了 showLines 参数
  • 添加了 render 参数
  • 为代码块添加了复制按钮
  • 为 Bitbucket 代码块添加了编辑链接

版本 1.3.0 - 2022-01-08

• 改进了相对链接的处理。现在在通过“浏览”URL嵌入时，它们指向“浏览”版本，而不是使用“原始”版本。

版本 1.2.0 - 2021-12-02

• 添加了对 扩展语法 Markdown 的支持

版本 1.1.0 - 2021-11-01

• 将 #embed 解析函数中的 github.com URL 标准化

版本 1.0.0 - 2021-09-30

针对 MediaWiki 1.35+ 的首次发布，具备以下功能

• 通过 #embed 解析函数嵌入 Markdown 文件
• 通过 #bitbucket 解析函数对 Bitbucket URL 提供特殊支持
• 通过 $wgExternalContentDomainWhitelist 设置限制源域名
• 通过 $wgExternalContentDomainWhitelist 设置限制文件扩展名
• 通过 $wgExternalContentBasicAuthCredentials 设置支持基本身份验证
• 通过 $wgExternalContentEnableEmbedFunction 设置关闭 #embed
• 通过 $wgExternalContentEnableBitbucketFunction 设置关闭 #bitbucket
• 通过 RefreshExternalContent.php 维护脚本来刷新所有嵌入内容
• 通过 Pages with external content 类别查看包含嵌入内容的页面
• 通过 Pages with broken external content 类别查看包含损坏嵌入内容的页面