轻松记录您
灵感和创意

markdown语法写readme

markdown语法写readme,编写README文档

首先需要注意的是,没有官方规定 readme 应该怎样去写,不需要将 readme 保持在同一长度。视具体情况,可以写得很长也可以很短,这取决于具体的项目。重要的是清晰准确地向用户传递必要信息,并避免默认读者已具备相关知识。

readme 要以精简的方式想用户传递信息,帮助他们配置并运行程序,要牢记我们是在为其他人而写。

1. README 剖析

开始是标题和说明,一两句话就好—-要确保清晰准确地表达项目精神。如果想做的更精致些,可以把项目 Logo 放进去。

下面继续补充理解代码所必须的信息—-比如对其他软件的以来、安装说明、通常用法、已知 BUG。

通常开发者会准备一个 getting started 或者 installation 部分,以在初始配置方面提供帮助,必要时引入事例代码,展示代码的正确用法。

2. 用 Markdown 便携易读的 README 文档

Markdown 能帮助建立良好的排版,自动转化为 HTML 进行显示。开发者们聚集的网站,如 GitHub,Stack,Overflow 甚至 Reddit 都支持 Markdown 语法实现快速方便的内容排版。Markdown 写 readme 的最大优势是排版后的文字非常适于快速阅读。

2.1 Markdown 基础知识

Markdown 是一种轻型标记语言,经常用于 README 的编写。它非常简单,大部分语法都很直观。

但实际上,Markdown 有许多不同的“方言”,就像在口语中一样。其中每种“方言”都被称为 Markdown 的“风格(flavor)”。这些方言大部分都大致相同,只有细微差别。

由于我是要用于 GitHub 上,因此这里使用的是 GitHub 风格的 Markdown。

2.1.1 设置文本加粗

要将文本设置为粗体,请用两个星号将其括起。因此,这行代码:

Isn’t today a **wonderful** day?

会显示为:Isn’t today a wonderful day?

2.1.2 设置文本斜体

要将文本设置为_斜体_,请在文本两旁添加下划线。因此,这行代码:

And in that moment I thought to myself: _Did I turn off the stove?_

会显示为:And in that moment I thought to myself: Did I turn off the stove?

与上一个示例相似,这样的代码更接近自然语言,原始文档浏览起来非常方便。

2.1.3 码,还是 不码?

内联代码标记,用于标注普通文本中的代码,为此,需要在代码文本两旁添加反撇号(,不是单引号)。因此,这行代码: You should use the ` tag.

会显示为:You should use the strong tag。这比直接显示 “You should use the strong tag.” 有意义多了。

2.1.4 标题顺序

标题更简单,对于 h1 到 h6 标签,只需要在文本前添加 #。Markdown 会根据 # 的数量生成响应的标题标记。例如:

## This is an h2.

## This is an h3.

未经允许不得转载:坚果之云 Markdown » markdown语法写readme
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍