如何为 Perl.com 写你的第一篇文章

2018年8月16日 by David Farrell

欢迎来到我们贡献系列的第二部分！第一篇文章解释了如何找到可以写的主题。本文将向您展示如何将文章提交给 Perl.com 以供发布。

我们的源代码托管在公共 GitHub 仓库 上，所以你需要做的第一件事是创建一个分支，以便拥有自己的副本。现在在本地克隆你的分支，你应该准备好开始做出你的更改。

创建您的作者数据

Perl.com 在 data/author 目录中存储作者配置文件数据。由于这是你的第一篇文章，你需要为自己创建一个条目。这是我的例子（data/author/david-farrell.json）

{
  "name": "David Farrell",
  "key": "david-farrell",
  "bio": "David is the editor of PerlTricks.com. An organizer of the [New York Perl Meetup](http://www.meetup.com/The-New-York-Perl-Meetup-Group/), he works for ZipRecruiter as a software developer.",
  "image": "/images/author/david-farrell.jpg"
}

• name - 你将在文章中显示的作者名称
• key - 你名称的独一无二的 ASCII 版本，这也应与你的作者数据文件名相匹配（例如：“david-farrell.json”）。在稍后文章的前置元数据中的 authors 数组中使用它
• bio - 你的个人传记，用 Markdown 格式编写，这样你就可以包括社交媒体和其他相关网站的超链接
• image - 宽度为 500 像素或更小，理想情况下小于 50kb 的正方形肖像/头像 jpeg 图像。这些图像放入 static/images/author 目录中。如果你没有图像或想使用一个，请使用 /images/site/avatar.png。

如果你设置正确，稍后你应该能在文章正文下方看到一个格式良好的个人资料

生成空文章文件

你可以使用 Perl 脚本 bin/new-article 生成空文章。它需要 --title、--category、--description 和 --author 参数。使用你刚刚创建的作者数据中的 author 键。它必须在根项目目录中运行，如下所示

$ bin/new-article --title 'Some New Perl Article' --author 'david-farrell' --desc 'There is more than one way to do it' \
  --category 'development'

如果上面的命令由于缺少 Perl 依赖项而失败，你可以通过 cpanm 安装它们

$ cpanm --installdeps .

优化文章前置元数据

每篇文章都以 前置元数据 开头，这已被 bin/new-article 脚本预先填充。你可以自由添加标签以帮助对文章内容进行分类。我们使用小写、ASCII 化的标签名（例如，请参阅 索引）。

其他两个可选的前置元数据属性是 thumbnail 和 image。如果你想用作文章封面图像的图像，请创建一个与文章文件名相同（不包含文件扩展名）的 static/images 目录下的目录，并将图像保存在那里。图像应该是横向的，并且小于 250kb。可以使用 bin/create-thumbnail 脚本为文章生成缩略图，它还将更新文章前置元数据，所以在运行它之前保存你的工作。

你可能想知道为什么 authors 属性是一个数组；这是为了能够在每篇文章中有多个作者！如果你与他人合作，创建他们的作者数据文件并在 authors 属性中包含他们的作者键。

撰写文章内容

关于撰写指导，我们的 风格指南 描述了我们希望 Perl.com 文章达到的标准。它还有一些使你的写作脱颖而出的技巧。所有文章都使用 GitHub Flavored Markdown 编写。我们使用了一些惯例

对于高亮显示的代码语法，使用带有编程语言名称的代码块，例如

```perl
  code
  code
  code
```

否则，只需使用代码块（围栏式或缩进式）即可，它将在深色背景上以等宽字体显示。这用于显示数据和终端命令。

文章副标题的大小为h2。因此，请使用以下结构

Subtitle goes here
------------------

使用mcpan简码创建CPAN模块的链接

[Business::ISBN]({{< mcpan "Business::ISBN" >}})

使用perldoc或perlfunc简码创建到官方Perl文档的链接

[perldelta]({{< perldoc "perldelta" >}})
[sort]({{< perlfunc "sort" >}})

可以使用relref创建对其他文章的内部引用。因此，要链接到“使用位数组节省空间”的文章

[save-space-with-bit-arrays](/article/save-space-with-bit-arrays/)

如果您不确定如何格式化某些内容，请在content/article目录中grep示例，并从中复制。

在本地查看您的文章

虽然用Markdown草拟文章很好，但它只有在您能在浏览器中看到其外观时才会变得生动。您可以在计算机上运行网站的本地版本。您需要安装Hugo。 警告 包管理器的hugo版本通常非常过时，您通常最好使用预编译的二进制文件。该网站已与v0.59.0版本进行测试，并应使用Hugo的最新版本构建。

从根项目目录启动网站的本地版本

$ hugo server --buildDrafts --buildFuture
...
Web Server is available at https://127.0.0.1:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

请注意程序输出——如果您看到任何错误，这通常意味着您的草稿文章格式不正确。一旦修复了这些问题，请使用浏览器导航到输出中显示的localhost地址，您应该会在计算机上看到运行在首页顶部的Perl.com版本，其中包含您的草稿文章！

如果您的页面没有出现，请确保Hugo能正确看到它

$ hugo list drafts

或者

$ hugo list future

润色您的文章

在将您的文章发送给我们之前，请检查您的文章

• 代码示例可以正常工作（测试它们！）
• 没有拼写错误
• 符合我们的风格指南

提示：我在写完第一稿后，发现第二天早上再看看它很有帮助。通过以全新的视角看待它，我经常发现可以做出的改进。

提交拉取请求

一旦草稿文章看起来不错，就可以提交拉取请求。提交您的更改，将它们推送到您的仓库，并通过GitHub向我们发送拉取请求。如果文章看起来合适，我们会合并请求并创建一个分支以进行编辑。从那时起，我们将对其进行审查，如果需要，对其进行编辑，并要求您审查我们的更改。如果您对它们感到满意，我们将发布您的文章。否则，我们可以继续编辑过程：通常不需要超过几个循环。我们的目标是保留您的声音，同时确保文章符合我们的标准。

一旦文章发布，我们将通知您，并在社交媒体上推广它。恭喜您，现在您是Perl.com的出版作者了！

封面图片由www.fidgetcircle.com提供