您是否撰写有关Javascript和Typescript的技术文章？ (Do you write technical articles about Javascript and Typescript?)

Do you write blog-posts about programming and software development? Great! That means you’re sharing your knowledge with fellow developers. In your technical post, you’ll want to include source code snippets. And of course, you want your source code to work. But when you co-develop your post and your code, your code is not yet finished when you start writing. When the source code changes, the struggle of keeping the snippets up-to-date begins. It’s a challenge but there is a way out.

您是否撰写有关编程和软件开发的博客文章？ 大！ 这意味着您正在与其他开发人员共享知识。 在您的技术文章中，您将希望包含源代码片段。 当然，您希望您的源代码能够正常工作。 但是，当您共同开发文章和代码时，开始编写代码时代码尚未完成。 当源代码更改时，保持片段最新状态的工作就开始了。 这是一个挑战，但有一条出路。

Note: This post was created with Publishable. You'll find the source file in the example-data folder in this repository (here)

注意 ：此帖子是使用Publishable创建的。 您可以在此存储库中的example-data文件夹中找到源文件( 此处 )

让我们潜入吧！ (Let’s dive in!)

Let’s say that this is the source code of your index.ts:

假设这是index.ts的源代码：

/** * @helloTag * Call `sayHello` to greet a person by her name. */function sayHello (name: string) { return `Hello ${name}!` }

With Publishable, you can refer to your code in your article (in Markdown):

使用Publishable ，您可以在文章(在Markdown中)中引用您的代码：

Have a look at the source code: <Source source="index" tag="helloTag"/> <Comment source="index" tag="helloTag"/>

This is the result (in Markdown):

这是结果(在Markdown中)：

```function sayHello (name: string) { return `Hello ${name}!` }```Call `sayHello` to greet a person by her name.

And this is the rendered result (it looks different depending on the renderer):

这是渲染的结果(根据渲染器的不同，它看起来也不同)：

为什么要参考代码和注释？ (Why Would I Want To Refer To Code And Comments?)

When writing technical articles about Javascript and Typescript, you’ll likely want to show some code. But how does the code get there?

在撰写有关Javascript和Typescript的技术文章时，您可能需要显示一些代码。 但是代码如何到达那里？

“You copy it from your IDE and paste it into the draft of your post.“

“ 您可以从IDE复制它，然后将其粘贴到帖子草稿中。 “

What do you do if the code changes? (And, it will change…)

如果代码更改，该怎么办？ (而且，它将改变……)

“You copy it from your IDE and paste it into the draft of your post. Again!“

“ 您可以从IDE复制它，并将其粘贴到帖子草稿中。 再次！ “

Once you finish your technical article, you will have copied and pasted your source code so many times that it’s going to be hard to tell whether all the code is up to date, and even harder to tell whether your code and the post text are in sync.

一旦您完成了技术文章，您将复制和粘贴您的源代码很多次，以至于很难分辨所有代码是否都是最新的，甚至更难分辨您的代码和帖子文本是否在其中。同步。

When you refer to your code and your code-comments, you ensure your article contains the actual source code. The source code you wrote, tested, and found to work.

当您引用代码和代码注释时，请确保您的文章包含实际的源代码。 您编写，测试并发现有效的源代码。

安装与配置 (Installation & Configuration)

Add Publishable as a devDependency to the project that contains the source code, you'll want to write about.

将Publishable作为devDependency添加到要编写的包含源代码的项目中。

npm install --save-dev publishable-tech

Publishable provides an executable script at ./node-modules/@publishable/tech/index.js

Publishable在./node-modules/@publishable/tech/index.js提供可执行脚本

Add a script to your package.json in which you call this script in NodeJs and pass start as an argument

将script添加到package.json中，在其中您可以在NodeJs中调用此脚本，并将start作为参数传递

"scripts": { "publishable":   "node ./node_modules/publishable-tech/index.js start" }

Publishable looks for the publishable.config.js file in the root directory of your project (in the same directory your package.json is in).

Publishable在项目的根目录(在package.json所在的目录中)中查找publishable.config.js文件。

module.exports = { contentPath: "./example-data/content", sourcesPath: "./example-data/src"}

The configuration supports the following paths:

该配置支持以下路径：

type IPublishableConfig = {/** * The `contentPath` is the (relative to the current * working directory) * path to the user's MD-content-folder */ contentPath: string;/** * The `sourcesPath` is the (relative to the current * working directory) * path to the user's source code folder */ sourcesPath: string;};

用 (Use)

Start Publishable during development with npm run publishable.

在开发过程中使用npm run publishable启动Publishable 。

Publishable loads your content and your sources and starts on localhost:8080. Publishable reloads automatically, Whenever you change your code or your content. Thus, you can see any change directly.

可发布可加载内容和源，并从localhost:8080开始。 无论何时更改代码或内容，可发布内容都会自动重新加载。 因此，您可以直接看到任何更改。

Write your Javascript and Typescript code. Do it the way you like and the way you usually write your code. Like this:

编写您的Javascript和Typescript代码。 以您喜欢的方式和通常的代码编写方式进行操作。 像这样：

function sayHello (name: string) { return `Hello ${name}!`}

If you want to refer to a piece of code, add a leading comment (starting with /**) and specify an arbitrary tag (starting with an@-sign). Like this:

如果要引用一段代码，请添加一个前导注释(以/**开头)并指定一个任意标记(以@ -sign开头)。 像这样：

/** * @helloTag * Call `sayHello` to greet a person by her name. */function sayHello (name: string) { return `Hello ${name}!`}

Add a markdown (.md)-file to the folder you specified as the contentPath in the publishable.config.js.

将markdown( .md )文件添加到您指定为publishable.config.js的contentPath的文件夹中。

You can use the normal Markdown syntax. And you can use two special tags:

您可以使用普通的Markdown语法。 您可以使用两个特殊标签：

1. The <Source />-tag adds source code snippet.

   <Source /> -tag添加源代码片段。

2. The <Comment />-tag adds a comment.

   <Comment /> -tag添加注释。

Both components take two properties:

这两个组件都具有两个属性：

• source specifies the source-file (without file extension) you want to add a snippet or a comment from.

  source指定要添加代码段或注释的源文件(不带文件扩展名)。

• tag specifies the snippet or comment to include

  tag指定要包含的代码段或评论

Of course, you can only place the tag into a comment. <Source /> will include the source code block the tagged comment refers to. Comments (starting with/**) preceed code blocks they refer to.

当然，您只能将tag放入注释中。 <Source />将包含标记注释所引用的源代码块。 注释(以/**开头)位于它们所引用的代码块之前。

For example, let’s say you have the following source code:

例如，假设您具有以下源代码：

function sayGoodbye(name: string) { return `Good bye ${name}!`}/** * @helloTag * Call `sayHello` to greet a person by her name. *//** * Another comment on `sayHello` */function sayHello (name: string) { return `Hello ${name}!`}

When you use <Source source="index" tag="helloTag /> in your .md-file, it will produce the following:

当您使用<Source source="index" tag="helloTag />在你.md -file，就会产生如下：

```function sayHello (name: string) { return `Hello ${name}!`}```

And when you use <Comment source="index" tag="helloTag />, it will produce this:

当您使用<Comment source="index" tag="helloTag /> ，它将产生以下内容：

Call `

<Comment /> only includes the comment that has the specified tag. But your source code block may have more than one comment. This way, you can control the parts of your comments you include or exclude.

<Comment />仅包含具有指定标签的注释。 但是您的源代码块可能有多个注释。 这样，您可以控制要包括或排除的注释部分。

Once you finished writing your code and your article, click the Export-button you'll find at the end of your article.

完成代码和文章的编写后，请单击文章结尾处的“ Export按钮。

It resolves all the references and provides the resulting Markdown file. You can use this file as documentation on GitHub or import it on any blogging platform.

它解析所有引用并提供生成的Markdown文件。 您可以将此文件用作GitHub上的文档，也可以将其导入任何博客平台。

结论 (Conclusion)

Keeping source code snippets in your technical article up-to-date manually is cumbersome and error-prone. Publishable lets you reference your source code and its comments in Markdown. Whenever your source code changes, it keeps your snippets synchronized.

手动更新技术文章中的源代码片段既麻烦又容易出错。 可发布可让您在Markdown中引用源代码及其注释。 只要您的源代码发生更改，它就会使您的代码片段保持同步。