扩展:语法高亮

此扩展已绑定在MediaWiki 1.21及以上版本 因此您不需要再次下载。 然而，您仍需要跟随提供的其他指导。

要在源代码编辑时对维基文本进行语法高亮，参阅CodeMirrorExtension:CodeMirror扩展或用户脚本Remember the dot和Cacycle。

MediaWiki扩展手册Manual:Extensions

SyntaxHighlight 发布状态：Extension status 稳定版
实现Template:Extension#type	Tag
描述Template:Extension#description	允许高亮显示在维基页面上的源代码
作者Template:Extension#username	Brion Vibber, Tim Starling, Rob Church, Ori Livneh
最新版本Template:Extension#version	continuous updates
MediaWikiTemplate:Extension#mediawiki	1.25+
数据更新Template:Extension#needs-updatephp	否
许可协议Template:Extension#license	GNU General Public License 2.0 or later
下载	下载扩展 Git [?]: 下载Git主线 浏览存储库 (GitHub) 提交历史 代码复核 README
参数Template:Extension#parameters * $wgPygmentizePath $wgSyntaxHighlightModels
标签Template:Extension#tags <syntaxhighlight>
使用的钩子Template:Extension#hook ContentGetParserOutputManual:Hooks/ContentGetParserOutput ParserFirstCallInitManual:Hooks/ParserFirstCallInit ApiFormatHighlightManual:Hooks/ApiFormatHighlight ResourceLoaderRegisterModulesManual:Hooks/ResourceLoaderRegisterModules
翻译SyntaxHighlight扩展如果在translatewiki.net可用
检查使用和版本矩阵。
问题Phabricator	开放的工作 · 报告错误

SyntaxHighlight扩展（语法高亮扩展），原先被称作SyntaxHighlight_GeSHi，使用<syntaxhighlight>扩展标签对源代码提供了丰富的格式。 它是由Pygments库提供支持的，并支持数百种不同的编程语言和文件格式。

就像<pre>和<poemExtension:Poem>标签，文本将按照输入的内容准确呈现且保留所有空格。

用法

当您安装本扩展后，您就可以在你的wiki使用“syntaxhighlight”标签。举个例子，

1 def quickSort(arr):
2 	less = []
3 	pivotList = []
4 	more = []
5 	if len(arr) <= 1:
6 		return arr
7 	else:
8 		pass

这是实现上面内容的维基代码：

<syntaxhighlight lang="Python" line='line'>
def quickSort(arr):
	less = []
	pivotList = []
	more = []
	if len(arr) <= 1:
		return arr
	else:
		pass
</syntaxhighlight>

在较旧的版本（MediaWiki 1.16 版本之前）中，这个扩展使用的是<source> 标签。 它现在仍然可以使用，不过 <syntaxhighlight> 也许可以帮助你获取比<source> 更准确的结果（例如XML语言）。

样式

如果您觉得标签里面的预览文字太大，您可以调整它通过把下面的代码拷贝到您wiki的 MediaWiki:Common.css中 （创建它如果不存在的话）：

/* 放置在这里的CSS会应用于全部皮肤 */
.mw-highlight pre {
	font-size: 90%;
}

代码块的外框可以通过在上方代码中插入一行border: 1px dashed blue;实现。 控制使用的字体也可以通过添加font-family: "Courier New", monospace;到上面的代码中。

语法高亮错误分类

该扩展将添加在<source>或<syntaxhighlight>标签中有错误lang属性的页面到一个追踪分类。 消息文字MediaWiki:syntaxhighlight-error-category决定了分类的名字，在本维基上为Category:Pages with syntax highlighting errors。

多数页面被加入该分类的错误是使用了<syntaxhighlight>或<source>标签但没有lang属性。

这些通常既可以替换为<pre>，也可以将lang="bash"或lang="text"添加到标签。

第二普遍的错误是使用lang="sh"或lang="shell"等不受支持的lang参数。 这些可以通过lang="bash"或lang="shell-session"替换。

参数

语言

lang="Name"属性定义了应使用什么词法分析器。 该语言会影响扩展如何高亮显示源代码。 pygments解析器区分大小写，所有语言都至少有一个大写字母（小写字母名称保留给gtags）。 参阅支持的语言这一章节获得关于受支持语言的详细内容。

def quickSort(arr):
    less = []

<syntaxhighlight lang="Python">
..
</syntaxhighlight>

指定了一个无效的或未知的语言名称，则该页面会被加入跟踪分类。 参阅语法高亮错误分类章节获取详细信息。

行号

line属性启用行号。

1 def quickSort(arr):
2 	less = []

<syntaxhighlight lang="Python" line>
..
</syntaxhighlight>

开始位置

start属性（与line相配合）定义了代码块的第一行行号。 例如，line start="55"将会使行号从55开始。

55 def quickSort(arr):
56     less = []

<syntaxhighlight lang="Python" line start="55">
..
</syntaxhighlight>

高亮

highlight属性将指定一行或多行将被标记（通过对指定的行显示不同的背景色）。 您可以指定多个行的数字通过逗号分隔（例如，highlight="1,4,8"）或使用一个连字符和两个数字表示范围（例如，highlight="5-7"）。 注意，行的数字将忽略任何start属性的重新标号。

3 def quickSort(arr):
4     less = []
5     pivotList = []
6     more = []
7     if len(arr) <= 1:
8         return arr

上面为下方代码的输出结果：

<syntaxhighlight lang="Python" highlight="1,5-7" start='3' line>
..
</syntaxhighlight>

内联

MediaWiki版本：

≥ 1.26

该属性表示源代码将作为段落的一部分内联（而不是自己的块）。 该选项在MediaWiki 1.26 版本开始可用。 为了保持向后兼容，enclose="none"也会有同样效果。

注意，换行符可以在标签开始和结束之间的任何空格处出现，若源代码带有class="nowrap"（在那些受支持的维基；见下方）或style=white-space:nowrap则是不换行的。

例如：

lambda x: x * 2是在Python的Lambda 表达式。

是下方的结果：

<syntaxhighlight lang="Python" inline>lambda x: x * 2</syntaxhighlight>是在Python的[[w:Lambda (programming)|Lambda 表达式]]。

class样式

当使用了inline时，指定class="nowrap"（在那些受到支持的维基上，而不是MediaWiki本身）不应在代码块内的空格处出现换行符。

例如：

没有class="nowrap"：

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxlambda x: x * 2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

With style="white-space:nowrap":

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxlambda x: x * 2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

style样式

style属性允许CSS属性被直接包含。 这相当于将块封装在<div>标签（不是<span>标签）中。 tab‑size属性不能够通过这种方式指定。它需要<span>标签封装，像下方高级段落中描述的样子。

例如：

def quickSort(arr):
	less = []
	pivotList = []
	more = []
	if len(arr) <= 1:
		return arr
	else:
		pass

是下方的结果：

<syntaxhighlight lang="Python" style="border:3px dashed blue">
def quickSort(arr):
	less = []
	pivotList = []
	more = []
	if len(arr) <= 1:
		return arr
	else:
		pass
</syntaxhighlight>

支持的语言

Pygments库为数百种计算机语言和文件格式提供支持。 简要的语言列表如下：

AppleScript, Assembly, Asymptote, Awk, bash, Befunge, Boo, BrainFuck, C, C++, C#, Clojure, CoffeeScript, ColdFusion, Common Lisp, Coq, Cryptol, Crystal, Cython, D, Dart, Delphi, Dylan, Elm, Erlang, Ezhil, Factor, Fancy, Fortran, F#, Gambas, GAP, Gherkin, GL shaders, Groovy, Haskell, IDL, Io, Java, JavaScript, Lasso, LLVM, Logtalk, Lua, Matlab, MiniD, Modelica, Modula-2, MuPad, Nemerle, Nimrod, Objective-C, Objective-J, Octave, OCaml, PHP, Perl, PovRay, PostScript, PowerShell, Prolog, Python 2.x and 3.x (incl. console sessions and tracebacks), R, REBOL, Red, Redcode, Ruby, Rust, S, S-Plus, Scala, Scheme, Scilab, Smalltalk, SNOBOL, Tcl, Vala, Verilog, VHDL, Visual Basic.NET, Visual FoxPro, XQuery, Zephir

（完整列表和完整的Pygments文档内容）和GeSHi支持的一些语言名称的映射（完整列表）。

Pygments 还没有提过对"wikitext" 或 "mediawiki" 提供词法分析 (phab:T29828) 。 请使用"html"、"xml"或"moin" 代替。

以下是GeSHi可以高亮显示的部分语言清单，在切换到Pygments之后不再支持语言的被用横线删去。

安装

The version of this extension bundled with MediaWiki 1.31 requires Python version 3 (python3) to be installed on the server. This is a change from the version bundled with MediaWiki 1.30, which used Python version 2 (python). Note that the python3 binary must be installed in the execution PATH of the PHP interpreter.

尽管它已经更新到Pygments（并不使用GeSHi），尽管它的名称已更新，但此扩展在内部仍使用以下所述的前一个文件名。

• 下载文件，并将其放置在您extensions/文件夹中的SyntaxHighlight_GeSHi目录内。

• 将下列代码放置在您的LocalSettings.php的底部：

  wfLoadExtension( 'SyntaxHighlight_GeSHi' );
  

• 在Linux中，请为pygmentize二进制文件设置可执行权限。

chmod a+x /path/to/extensions/SyntaxHighlight_GeSHi/pygments/pygmentize

• Y 完成 – 在您的wiki上导航至Special:Version，以验证扩展已成功安装。

致使用MediaWiki 1.24或更早版本的用户：

上面的说明介绍的是安装此扩展的新方法，它使用wfLoadExtension() 如果您需要在早期版本（MediaWiki 1.24和更早版本）中安装此扩展，而不是wfLoadExtension( 'SyntaxHighlight_GeSHi' );，您需要使用：

require_once "$IP/extensions/SyntaxHighlight_GeSHi/SyntaxHighlight_GeSHi.php";

当安装自Git时，请注意在MediaWiki 1.26 版本开始，该扩展需要Composer。

所以，在从git安装之后，切换到包含该扩展的目录。例如："../extensions/SyntaxHighlight_GeSHi/"并运行composer install --no-dev，或在更新时：composer update --no-dev。

或者最好将"extensions/SyntaxHighlight_GeSHi/composer.json"添加到在Wiki根目录下的"composer.local.json"文件中，例如：

{
	"extra": {
		"merge-plugin": {
			"include": [
				"extensions/SyntaxHighlight_GeSHi/composer.json"
			]
		}
	}
}

现在运行composer update --no-dev。 Voilà!

当通过FTP上传扩展时，请确保将pygments/pygmentize文件作为binary传输。

配置

Linux

• $wgPygmentizePath （可选）：Pygments包中pygmentize的绝对路径。 默认情况下，扩展中附带了Pygments包，$wgPygmentizePath指向默认了Pygments包，但如果需要，您可以指向不同的版本。 例如：$wgPygmentizePath = "/usr/local/bin/pygmentize";。
• $wgSyntaxHighlightModels：对一些维基页面配置默认的语法分析器。 默认情况下它会高亮显示javascript和css页面。 额外的内容模型可以通过扩展名配置（例如：Lua、JSON等）。

Windows

• 若您在一台Windows主机上运行MediaWiki，您需要设置Pygmentize.exe的位置$wgPygmentizePath = "c:\\Python27\\Scripts\\pygmentize.exe";。
  • 若没有pygmentize.exe，从命令行运行在Scripts目录中的easy_install Pygments来生成文件。

若您在使用附带的pygmentize二进制文件（extensions/SyntaxHighlight_GeSHi/pygments/pygmentize），确保您的网络服务器允许执行它。 若您的主机商不允许添加可执行文件到站点目录，安装python-pygments并添加$wgPygmentizePath = pygmentize到LocalSettings.php中。

问题排除

找升级到MediaWiki 1.26 版本及其以后，一些用户开始报告与这个扩展的问题。 There could be cases, when some languages, such as Lua might not get highlighted and by turning on debugging, MediaWiki would throw out the error, Notice: Failed to invoke Pygments: /usr/bin/env: python3: No such file or directory.

• 尝试在LocalSettings.php指定$wgPygmentizePath为外部pygmentize二进制文件。

• In shared hosting environments with cPanel, this can be done by setting up a new Python application through the "Setup Python App" menu, and activating the virtual environment for the app through SSH (source /virtualenv/python/3.5/bin/activate). After this, the Pygments module can be added to the Python app, for which navigate to the virtual environment path (cd virtualenv/python/3.5/bin/), download and install Pygments (./pip install Pygments) and then activate the module by adding "Pygments" under the "Existing applications" section of the "Setup Python App" menu. This will create the required file at path: virtualenv/python/3.5/bin/pygmentize

• 获取更多建议和信息，请参见phabricator task。

可视化编辑器集成

该插件可以使用可视化编辑器直接编辑。 一个对话框会被打开，当一个用户想要编辑source或syntaxhighlight段落。 要使其工作，可视化编辑器必须被安装且从最新git版本被配置，与Parsoid相同。 该功能在较老的Parsoid版本中随机地无法使用。 See Extension:SyntaxHighlight/VisualEditor for details

高级

不像<pre>和<code>标签，HTML字符实体（例如$nbsp）不需要&字符转意为&2。

Like the <pre> tag but unlike the <code> tag, tags within the range (other than its own closing tag) need not have the < symbol escaped as <, nor does wikitext need to be escaped with a <nowiki> tag.

Furthermore, while <pre> assumes tab stops every 8 characters and renders tabs using actual spaces when the rendered text is copied, <syntaxhighlight> uses 4-space tab stops (except Internet Explorer, which uses 8) and preserves the tab characters in the rendered text; the latter may be changed using an enclosing <span style="-moz-tab-size:nn; -o-tab-size:nn; tab-size:nn;"> tag (not <div>, and not using its own style attribute). The -moz- prefix is required for Firefox (from version 4.0), and the -o- prefix is required for Opera (from version 10.60 to version 15). (Note that the wiki editing box assumes 8-space tabs.) This applies only to actual saved pages; previews generated through an edit box or Special:ExpandTemplates may differ.

另请参阅

• Pygments – Python syntax highlighter
• 相关扩展：
  • Extension:GoogleCodePrettifyExtension:GoogleCodePrettify – 使用谷歌代码美化库的语法高亮扩展。
  • Extension:SyntaxHighlighterExtension:SyntaxHighlighter – 使用SyntaxHighlighter库的语法高亮扩展。
  • Extension:ViewFilesExtension:ViewFiles – 一个依赖于这个扩展的扩展，支持通过一个特殊页面查看文件的高亮文本。