源码模式

MDN 编辑器有个重要的按键,用来切换到源码编辑模式。此模式下,你可以看到正在编辑的文章的 HTML。这个指引使你了解 MDN wiki 源码编辑模式做什么,什么应该做,但更为重要的是,什么是不应该做的。

在你考虑使用源码模式之前,请注意我们强烈建议你不要使用源码模式。如果您只是为了强行符合我们的样式规范,你不应该去使用源码模式。我们确实有一些需求不启用源码模式无法做到。记得查看Warnings and caveats

启用源码模式

启用源码模式很简单。在编辑器工具栏的左上角,点击“Source”或“原始碼”按钮。

Partial screenshot of the editor toolbar, with the Source mode button highlighted

对于格式化、图片之类的功能,很可能源码模式没有 WYSIWYG (所见即所得)好用,因为你可能需要滚动很远才能找到编辑器中相关源码的位置。

警告

综上所述,你应该极少会需要用到源码模式。只有一些极个别的事情才必须由修改源码实现。最终,我们会更新编辑器界面,为你展示你的修改。

MDN贡献者指南中未明确描述的所有内容均不应添加到源代码中。这意味着:

  • 不要使用自定义字体和样式。若不是标准的一部分,请勿使用。
  • 不要使用特殊颜色。若不是标准视觉样式,请修改为我们提供的样式。

源码模式下编辑

一旦启用源码模式,你将可以编辑 wiki 页面的原始 HTML。虽不受编辑器约束,您应竭尽所能保持您的工作与样式指南一致,并且可以安全可靠的工作。

通常,您应该是在源码模式中做一些短暂的调整,而不是长时间的撰写页面。

不幸的是,Tab 键在源码模式中无法使用,请输入两个空格来代替。

若您使用 MDN 不允许的 HTML 元素和属性,它们会在你保存时直接被移除。此外,文档还将重新被格式化,以使之符合预期。

合理使用源码模式

在一些个别的情况下,使用源码是唯一能遵循MDN格式规范的方式。这一节涵盖了这些情况,并说明了如何在不破坏其他东西的前提下,正确使用这些功能。

在示例代码中高亮代码行

在用工具栏的块组中的PRESyntax Highlighter建立的示例代码片段块中,你会希望让某几行代码更引人注目一些。唯一实现这种事项的方式是开启源码模式,找到包含此部分代码的<pre>块,然后编辑<pre>标签的class属性,加上一个highlight组件,像下面这种格式:

  • highlight[lineNum1, lineNum2, ..., lineNumN]

例如,如果现在的标签为<pre class="brush: js">,然后你想往第4行和第7行加个高亮,你可把它改为<pre class="brush:js; highlight:[4,7]">

我们看个更复杂的示例:

高亮前 高亮后
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var path1 = new Path2D();
path1.rect(10, 10, 100, 100);

var path2 = new Path2D(path1);
path2.moveTo(220, 60);
path2.arc(170, 60, 50, 0, 2 * Math.PI);

ctx.stroke(path2);

这里的<pre>标签为:<pre class="brush: js">

var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var path1 = new Path2D();
path1.rect(10, 10, 100, 100);

var path2 = new Path2D(path1);
path2.moveTo(220, 60);
path2.arc(170, 60, 50, 0, 2 * Math.PI);

ctx.stroke(path2);

然后这里的<pre>标签已经改为了:<pre class="brush: js; highlight:[4,7]">

没有对应工具栏按钮的样式

MDN上我们用的一些样式通过通常的用户界面是无法实现的。好消息是,这些不是很常见。示例如:

  • 要应用“keyboard”样式于其上的话,你需要将<kbd>元素中的键名的文本括上。我们还没有实现这个功能的用户界面,所以调到源码模式,把键名括在<kbd>中。 例如,如果源码是:
    <p>Press the <kbd>Enter</kbd> key to start the countdown.</p>

    输出结果就是:

    Press the Enter key to start the countdown.

  • 用于特定页面的一些很不常用的样式也需要手动加上,这尤其在一组盒子上常见。这就是我们用宏来帮助自动建立诸多入口页面组件的缘故。