扩展:语法高亮

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:SyntaxHighlight and the translation is 94% complete.

Other languages:
Deutsch • ‎English • ‎日本語 • ‎русский • ‎Türkçe • ‎中文
要在源代码编辑时对维基文本进行语法高亮,参阅CodeMirrorExtension:CodeMirror扩展或用户脚本Remember the dotCacycle
此扩展已绑定在MediaWiki 1.21及以上版本 因此您不需要再次下载。 然而,您仍需要跟随提供的其他指导。
该扩展原先被称为SyntaxHighlight_GeSHi,因为它使用GeSHi提供语法高亮显示。 从2015年6月开始使用Pygments
MediaWiki扩展手册Manual:Extensions
Crystal Clear action run.svg
SyntaxHighlight

发布状态:Extension status 稳定版

SyntaxHighlighting with Pygments.png
实现Template:Extension#type Tag
描述Template:Extension#description 允许高亮显示在维基页面上的源代码
作者Template:Extension#username Brion Vibber, Tim Starling, Rob Church, and 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
下载
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 int x = 0;
2 Console.WriteLine("结果是:"+ x);
<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>标签封装,像下方高级段落中描述的样子。

例如:

#include <stdio.h>
int main()
{
	printf ("Hello world!");
	return 0;
}

是下方的结果:

<syntaxhighlight lang=c style="border:3px dashed blue">
#include <stdio.h>
int main()
{
	printf ("Hello world!");
	return 0;
}
</syntaxhighlight>

支持的语言

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

AppleScript, Assembly, Asymptote, Awk, 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#, 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之后不再支持语言的被用横线删去。


安装

gotcha
  • 下载文件,并将其放置在您extensions/文件夹中的SyntaxHighlight_GeSHi目录内。
  • 将下列代码放置在您的LocalSettings.php的底部:
    wfLoadExtension( 'SyntaxHighlight_GeSHi' );
    
  • Linux中,请为pygmentize二进制文件设置可执行权限。
chmod a+x /path/to/extensions/SyntaxHighlight_GeSHi/pygments/pygmentize
  • YesY 完成 - 在您的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 版本及其以后,一些用户开始报告与这个扩展的问题。

  • 尝试在LocalSettings.php指定$wgPygmentizePath为外部pygmentize二进制文件。
  • 获取更多建议和信息,请参见phabricator task

可视化编辑器集成

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

高级

不像<pre><code>标签,HTML字符实体(例如 )不需要&字符转意为&。 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 &lt;, 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).[1] (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.

另请参阅

Footnotes