在 WordPress 网站上发布代码块

最初发布于 2014 年 2 月，现已更新/更正/扩展。

因此，您已安装 WordPress 并希望撰写关于代码的博客。太棒了！您是一位英雄，我代表我自己和所有程序员表示感谢。以下是在您实际发布代码块时需要执行的操作和需要考虑的事项。

“代码块”的 HTML

有一个专门用于代码的元素：<code>。我认为语义上正确的方法是将所有代码都用它包装起来。浏览器的默认样式表将其作为内联元素，我建议您保持这种方式，以便您可以在句子中使用它，就像我在上一句中所做的那样。

但是您需要使用块级元素来包装代码块。<pre> 是完美的元素，因为它可以自然地保留空白字符。“Pre”代表“预格式化文本”。多个空格将呈现为多个空格，而不是像 HTML 中通常那样折叠成单个空格。这对于代码来说非常完美，因为您可能希望在代码块中使用缩进，并且您不希望诉诸任何   的花招。

所以

<pre><code>Your 
   
   block
  
       of

   code
 
 here.</​code></​pre>

关闭“视觉”编辑器

默认情况下，WordPress 允许您在编辑器中切换“视觉”和“文本”选项卡。

对于您来说，必须关闭视觉编辑器。您永远不会使用它。您希望完全控制您正在编写的文本，并希望在保存时保持其原样。

在**用户 > 个人资料**下关闭它。

您是否要使用 Markdown 撰写博客？

在 CSS-Tricks 上，我不使用 Markdown，但如果我能回到过去，我可能会使用。在我之后创建的大多数博客中，我都使用了 Markdown 并更喜欢它。如果您打算使用 Markdown，我建议您使用 Jetpack 的 Markdown 功能。

要在 Markdown 中发布代码块，一种方法是在每一行的开头缩进四个空格，如下所示

Yadda yadda yadda. I'm a *paragraph* in Markdown. Here's a [link to Google](http://google.com). Here's a block of code:

    <div>
       <p>I'm some code.</p>
    <div>

Another paragraph here.

手动执行此操作很快就会变得很麻烦。因此，您需要将编辑器按钮替换为 Markdown 按钮。看起来插件 Markdown Quicktags 可以做到这一点。

使用 Markdown 的好处是您不必担心转义代码。因此，这些尖括号不会构成渲染威胁，Markdown 会为您转义它们。换句话说，上面 HTML 示例中的所有尖括号 (<) 将转换为 <，从而在屏幕上显示为尖括号，而不是让浏览器误以为 HTML 标签即将出现。

在发送到浏览器之前，上面的 Markdown 示例将转换为以下内容

<p>Yadda yadda yadda. I'm a <em>paragraph</em> in Markdown. Here's a <a href="http://google.com">link to Google</a>. Here's a block of code:</p>

<pre><code>&lt;div&gt;
   &lt;p&gt;I'm some code.&lt;/p&gt;
&lt;div&gt;</code></pre>

<p>Another paragraph here.</p>

如果您有兴趣使用 Markdown 撰写博客，您可以选择一些方法。Automattic 创建并维护的插件 Jetpack，现在将其作为其众多产品的一部分提供。目前，我在 CSS-Tricks 上使用 WP-Markdown（我知道我说过我不使用 Markdown，但我确实在论坛和评论中使用，而不是博客）。

我个人没有尝试过的两个插件是 Typewriter 和 Markdown on Saved Improved。

但是，这里有一个相当大的限制。请注意，四个空格的缩进转换为 <pre><code> 块，但此处没有机会向这些标签添加属性。属性（如类和 data-* 属性）是一种常见需求。您可能希望使用语法高亮显示器（我们稍后将讨论这些内容），它需要一些属性才能发挥作用。或者，您可能希望以某种方式通过语言标识代码块。

与缩进相比，更方便的是，许多 Markdown 的“风格”（包括 Jetpack 版本）支持代码围栏，即将代码块放在三个反引号中

```
<div>
  <p>I'm some code.</p>
<div>
```

我会称之为直接改进。在编写时跳入代码块更容易，而不必担心缩进问题。此外，代码本身有自己的缩进，因此从左对齐开始很好。

您还可以直接在 Markdown 语法中指定语言。因此，我们的示例可以是

```html
<div>
  <p>I'm some code.</p>
<div>
```

这将得到

<pre><code class="html">&lt;div&gt;
  &lt;p&gt;I'm some code.&lt;/p&gt;
&lt;div&gt;
</code></pre>

如果您不使用 Markdown，则需要转义代码。

CSS 代码块很少需要转义，但 HTML 肯定需要转义，JavaScript 有时包含 HTML（以及几乎所有后端语言），因此您不妨假设所有代码都需要转义。

您可以手动将所有 < 转换为 &lt;，但这会让您感到疯狂。您可以使用 Postable 等工具复制粘贴要转义的代码块，但这也很慢且繁琐。

我更喜欢使用名为 Code Markup 的插件来实现此目的。它会自动转义在 <code> 标签中找到的任何内容，因此您永远不必考虑它。

因为我在此站点上使用了该插件，所以我可以执行以下操作

<pre data-lang="HTML"><code class="language-markup"><div>
  <p>I'm some code.</p>
<div></​code></​pre>

并且效果很好。无需转义。完全控制属性。

处理语法高亮显示

请记住，语法高亮显示代码块的一种选择是不进行语法高亮显示。当然，这将是最快和最简单的方法。但您可能希望进行高亮显示。我个人喜欢它。我喜欢它看起来的样子。以下是一些选择。

任何语法高亮显示器实际上发生的事情是，代码片段最终会被包装在 <span> 中，并带有类名称，您可以使用 CSS 对其进行着色。选择取决于功能。

Prism.js

在 CSS-Tricks 上，我使用（并推荐）Lea Verou 的 Prism，因为它可以开箱即用。它体积小、速度快，并且（我最喜欢的）具有用于样式设置的合理类名。在下载时，您可以选择要支持的语言。

我还使用了该转义插件，这意味着我无需转义代码标签内的 HTML，因此它看起来像这样

<pre><code markup="tt" class="language-markup"><div>
  <p>I'm some code.</p>
<div></​code></​pre>

代码标签上的 class="language-markup" 是 Prism 用于语法高亮显示的内容。默认情况下，它会自动处理找到的所有具有该类名模式的代码，但如果您想自己处理，则可以使用 API。

Prettify

一个非常流行的工具是 google-code-prettify。要语法高亮显示代码块，请在代码或 pre 标签上添加 class="prettyprint"。

它的文件大小比 Prism 大，但一个优点是它可以自动检测语言（并支持大量语言），因此它应该适用于几乎所有内容，而无需您指定。

其他

稍微深入研究一下，还有很多我无法保证但似乎也能解决问题的工具：Rainbow、SyntaxHighlighter、Chili（jQuery）、JSHighlighter、jQuery.Syntax（jQuery）、GeSHi、Lighter（MooTools）、highlight.js、SHJS 和 Pygments（Python）。

决定

为了在这些选项中做出选择，你可以考虑以下几点

• 我主要需要支持哪些语言？
• 我是否需要显示行号？
• 我是否需要在代码中插入链接？
• 我是否希望能够突出显示代码的某些部分或行？
• 我是否有需要支持的遗留代码块？它们的格式是什么？
• 代码是否易于复制和粘贴？我是否希望添加一些辅助功能？
• 客户端语法高亮是否可以，或者我是否希望它在服务器端进行？

视觉上识别代码块

我认为能够一目了然地看出代码块是什么类型是一个不错的功能。在这个网站上，我通过代码块本身的一个属性来实现这一点，然后将该属性的值作为显示的一部分进行样式设置。你可以在此处显示的大多数代码块中看到它的实际效果（假设你正在查看网站本身，而不是在其他地方阅读其联合内容）。

以下是如何在代码块上视觉显示特定属性的方法（样式完全由你决定！）

pre[data-language-display]:before {
  content: attr(data-language-display);
}

处理遗留代码

如果你在一个网站上已经有一堆代码块，我仍然建议选择一个你喜欢的并且具有所需功能的语法高亮器，以便当前和将来使用。然后找到一种方法使其适用于旧的代码块。

例如，假设我有一个像这样标记的遗留代码块

<pre><code class="javascript">
  var thing = document.getElementById("thing");
</​code></​pre>

这不是 Prism 正确的类名。因此，我可能会使用 jQuery 执行类似的操作

$("code.javascript")
  .removeClass("javascript")
  .addClass("language-javascript");

并确保该 JavaScript 在 Prism 之前运行。我还可以借此机会使用 $.trim() 修剪代码，因为如上所述，顶部和底部有一个额外的换行符，这可能会影响代码块的样式。

我只是举个例子。总的来说，意思是：你可以根据需要操作遗留代码块以适应新的格式。

使用插件

有很多 插件 可以做到这一点。这篇文章主要针对自己处理代码高亮，因为这通常是我喜欢的控制方式。但我相信有很多优秀的插件可以做到这一点。我不敢推荐任何一个，但我会寻找以下几点

• 良好的评价/评分/看起来像是更新过的
• 不会让你对代码块做任何奇怪/专有的操作。例如，使用[shortcode]。这将使你永远绑定到该插件。
• 支持你需要的语言和功能（并且只支持你需要的功能，不会加载所有东西）。

第三方帮助

在 CodePen 创建 嵌入式笔 功能时，我们知道在博文中显示演示和代码有点麻烦，因此我们着手简化这一过程。

这是一个嵌入式笔的示例，默认显示 CSS 代码

查看笔 使用 动态图像着色 由 Noah Blon (@noahblon) 在 CodePen 上。

我不需要担心语法高亮、转义或任何其他事情，并且可以获得显示渲染演示的额外好处。

许多其他代码编辑器网站也提供嵌入式代码，例如 JSFiddle 和 JSBin。 GitHub Gists 也可用于此目的。我可能最喜欢使用第三方工具的原因是，你可以去那里更新演示，而博客文章会自动包含新的代码。你无需在两个地方更新内容。

---

你是否有自己处理 WordPress 网站上代码块的方法？欢迎分享。