百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 编程网 > 正文

学习 GitHub 风格的 Markdown 语法和格式化 - 带有示例

yuyutoo 2024-12-24 16:33 1 浏览 0 评论

Markdown 是一种轻量级、开源、易读易写的文本格式化方法,你可以在任何 IDE 或编辑器中将其作为纯文本使用。

在 GitHub 上写作时,你可以使用 Markdown 语法和 HTML 元素来扩展 Markdown 的功能。你可以在 GitHub 的各个地方使用 Markdown 语法,比如 README 文件、wiki、评论、拉取请求以及创建问题时。

对于每个软件开发者来说,学习 Markdown 是你职业生涯道路上的一个关键步骤。

为了增强 Markdown 的基本功能,GitHub 添加了一些自定义功能,并创建了 GitHub 风格的 Markdown。通过这个,你可以通过提及用户、问题和 PR 引用以及添加表情符号来轻松与其他用户在拉取请求和问题中进行交流。

本文将教你 GitHub 风格的 Markdown 的基础知识,以便你能够在你的项目中开始使用它。

(本文视频讲解:java567.com)

GitHub 风格的 Markdown 语法

GitHub 风格的 Markdown 语法分为两个部分。

  1. 基本格式化语法
  2. 高级格式化语法

我们将在下面详细讨论每一个。

基本格式语法

基本格式语法适用于所有人。它包含了诸如标题、代码、图片、引用、链接等基本要素,这些是你在撰写文档时需要了解的内容。

  1. 标题
  2. 段落
  3. 注释
  4. 文本样式
  5. 引用
  6. 代码
  7. 链接
  8. 图片
  9. 列表
  10. 提及个人和团队
  11. 引用问题和拉取请求
  12. 使用表情符号
  13. 脚注
  14. 警告

请注意,代码示例大多来自于 GitHub 的文档。

标题

你可以使用 # 符号来创建标题。一个 # 创建一个 H1 标题,两个创建一个 H2 标题,依此类推,就像这样:

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

在 Markdown 中创建标题。

段落

要创建段落,你可以使用空行来分隔一行或多行文本或段落。

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam est odio, commodo id diam sed, pulvinar sagittis tortor. Nam vestibulum purus eros. Sed congue, mi id pretium auctor, nibh augue iaculis arcu, eu tristique quam dolor at erat.

Quisque vel odio condimentum, mollis sem vitae, porta diam. Praesent ligula elit, condimentum eget ex sed, commodo sollicitudin sapien.

Proin volutpat faucibus nulla. Nullam eros sem, ultricies gravida nunc nec, dapibus posuere nisl. Nunc lacinia elementum turpis in pharetra. Aenean eu neque eros.

在 Markdown 中创建段落。

注释

注释几乎在每种编程语言中都可用。它们帮助开发者写下注释并向他们的代码添加额外信息,帮助其他开发者理解正在发生的事情以及代码如何运行。

要在 Markdown 中添加注释和额外信息,请使用以下语法:<!--- 包裹文本 --->

以下是一个示例:

<!-- 这段内容不会出现在渲染后的 Markdown 中 -->

在 Markdown 中创建注释。

文本样式

你可以对文本应用基本样式,比如粗体、斜体、删除线、下标或上标,以提高可读性并更清晰地传达你的意思。

  1. 对于 粗体,你可以使用以下语法:**你的文本**
  2. 对于 斜体,你可以使用以下语法:*你的文本* 或 _你的文本_
  3. 对于 删除线,你可以使用以下语法:~~你的文本~~
  4. 对于 下标,你可以使用以下语法:下标<sub>文本</sub>在此。
  5. 对于 上标,你可以使用以下语法:上标<sup>文本</sup>在此。
## 粗体

**你的文本**

## 斜体

*你的文本*
_你的文本_

## 删除线

~~你的文本~~

## 下标

下标<sub>文本</sub>在此。

## 上标

上标<sup>文本</sup>在此。

引用

块引用或引用是格式化为让读者知道你在引用某人的句子或段落。要在 Markdown 中创建块引用,可以使用 > 符号。

> 这是引用的文本

在 Markdown 中创建块引用或引用。

代码

Markdown 文件支持两种类型的代码示例:内联代码块

  1. 要在 Markdown 文件中添加代码块,请使用以下语法:你的代码
  2. 要将内联代码添加到 Markdown 文件中,请使用以下语法:你的代码
## 代码块

// ES5 语法 var multiply = function(x, y) { return x * y; };

// ES6 箭头函数 var multiply = (x, y) => { return x * y; };

// 或者更简单地 var multiply = (x, y) => x * y;


## 内联代码 

JavaScript 提供三种不同的值比较操作:使用 `===` 进行严格相等比较,使用 `==` 进行宽松相等比较,以及使用 `Object.is()` 方法。

要在代码块中支持代码高亮,你可以在三个反引号之后添加一个可选的语言标识符(就像下面的示例中的 JavaScript 一样):

## 代码块

```javascript

// ES5 语法
var multiply = function(x, y) {
  return x * y;
};

// ES6 箭头函数
var multiply = (x, y) => { return x * y; };

// 或者更简单地
var multiply = (x, y) => x * y;   

创建一个带有语法高亮示例的代码块。

链接

Markdown 文件将链接分为两类:内联相对

内联链接

要在 Markdown 文件中创建内联链接,请将链接文本放在方括号 [ ] 中,紧接着在括号 ( ) 中放置 URL。

This site was built using GitHub Pages.

相对链接

相对链接与内联链接类似,但在 [] 部分有所不同:[] 部分包含存储库中文件的路径。

你可以使用相对链接来链接两个文件:例如,将 CONTRIBUTING 文件链接到 README 文件中。

[贡献指南](docs/CONTRIBUTING.md)

/ 开头的相对链接将相对于存储库根目录。你可以使用所有相对链接操作符,比如 ./../

[贡献指南](../docs/CONTRIBUTING.md)

图片

要在 Markdown 文件中添加图片,首先在 [] 中放置 alt 文本,然后在括号 () 中放置图片链接。

看起来像这样:

列表

列表有助于按顺序记录重要信息,这对读者非常重要,使人们易于理解和查找信息。

Markdown 文件支持三种类型的列表:

  1. 有序列表
  2. 无序列表
  3. 任务列表

有序列表

第一种类型是有序列表。要创建有序列表,请以数字加句点开头。

1. one
2. two
3. three
4. four

创建一个有序列表

无序列表

第二种类型是无序列表。要创建无序列表,请使用 -+*(取决于你的喜好 - 它们都会呈现为无序列表):

* 第一项
* 第二项
* 第三项
* 第四项


- 第一项
- 第二项
- 第三项
- 第四项

+ 第一项
+ 第二项
+ 第三项
+ 第四项

创建一个无序列表

任务列表

第三种类型是任务列表。要创建任务列表,列表项以连字符开头,后跟一个空格,然后是方括号 []。你可以在方括号 [x] 中使用 x 来标记任务为已完成。

- [x] #739
- [ ] https://github.com/octo-org/octo-repo/issues/740
- [ ] 当所有任务完成时,为体验添加喜悦 :tada:

在 markdown 中添加任务列表

提及个人和团队

在 markdown 中提及用户和团队

要在 GitHub markdown 文件中提及个人或团队,请键入 @,然后写入用户名或团队用户名。

## 个人或个体用户名

@officialrajdeepsingh,请查看以下更改。

## 团队或公司
博客主题部分由 @frontendweb 维护

在 markdown 中提及其他用户和团队

引用问题和拉取请求

问题和拉取请求

要在 GitHub markdown 文件中提及问题和拉取请求,请键入 #,然后键入问题或拉取请求的编号或标题。然后按 tab 键或 enter 键以完成高亮显示的结果。

删除默认 _target blank 中的徽标 #93

在 markdown 中提及拉取请求

使用表情符号

在 markdown 中添加表情符号。

要在你的写作中添加表情符号,请在两个冒号之间键入表情符号的代码。如果只键入 :,GitHub 上将显示建议的表情符号列表。

找到你想要的表情符号后,按 Tab 键或 Enter 键选择高亮显示的结果。

不要忘记给我们的仓库点颗星! :star:

在 markdown 中添加表情符号

脚注

要添加脚注引用,请在方括号 [^1] 内添加一个尖号和一个标识符,使用以下语法:

这是一个简单的脚注,[^1] 这是一个更长的脚注.[^bignote]

[^1]: 这是第一个脚注。

[^bignote]: 这是一个包含多个段落和代码的脚注。

在 markdown 中创建一个脚注

警告

警告是基于块引用语法的 Markdown 扩展,你可以使用它来强调重要信息。

GitHub 风格的 Markdown 支持五种类型的警告:[!NOTE][!TIP][!IMPORTANT][!WARNING][!CAUTION]。你可以使用其中任何一个:

> [!NOTE]
> 有用的信息,用户在浏览内容时应该知道。

> [!TIP]
> 提供更好或更容易做事的有益建议。

> [!IMPORTANT]
> 用户为了实现目标所需的关键信息。

> [!WARNING]
> 紧急信息,需要用户立即注意以避免问题。

> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。

在 markdown 语法中,GitHub 风格的 Markdown 支持的警告列表。

警告语法在浏览器中如下所示:

在 markdown 中添加警告示例。

高级格式化语法

这个高级格式化语法部分包含了一些高级用法,比如添加图表和表格、折叠节、数学表达式等。

  1. 创建表格
  2. 创建折叠节
  3. 创建图表
  4. 数学表达式

创建表格

要在 Markdown 中创建表格,你可以使用管道 | 和连字符 -。连字符用于创建列标题,而管道用于分隔列。

| 第一标题 | 第二标题 |
| --------- | --------- |
| 内容单元 | 内容单元 |
| 内容单元 | 内容单元 |

在 markdown 中创建表格

表格在浏览器中的样子如下:

Markdown 中的表格示例。

创建折叠节

要在 markdown 文件中创建一个折叠节,你可以使用 <details> 标签。这个标签是一个 HTML 元素,你可以很容易地使用它来扩展 GitHub 风格的 Markdown 的功能。下面是它的工作原理:

<details>
  <summary>点击这里。 </summary>
   
   ### 在这里添加消息

   你可以在折叠节中添加文本。 

   你也可以添加图片或代码块。

   ```ruby
     puts "Hello World"
   ```
  
</details>

在 markdown 中创建一个折叠节

在浏览器中,折叠语法看起来像这样:

Markdown 中的折叠示例。

创建图表

要向 Markdown 文件中添加图表,使用三个反引号并将它们包裹在四个反引号内。然后,告诉使用了哪个标识符(Mermaid、GeoJSON、TopoJSON、ASCII STL)来创建图表。

GitHub 支持使用四种语法来创建图表:mermaid、geoJSON、topoJSON 和 ASCII STL。

  1. Mermaid
  2. GeoJSON 和 TopoJSON
  3. ASCII STL

Mermaid

Mermaid 是一个受 Markdown 启发的工具,可以将文本渲染成图表。你可以使用 Mermaid 创建流程图、序列图、饼图等。

GitHub 风格的 Markdown 扩展了使用 Mermaid 的功能。

你可以在 Markdown 中创建流程图、序列图、饼图等。GitHub 会处理剩下的部分。那么你如何在屏幕上渲染图表呢?

```mermaid
graph LR;
   A --  和 --> B -- 到 --> C
```

创建 Mermaid 示例

在浏览器中,mermaid 语法看起来像这样。

Markdown 中的 Mermaid 示例。

GeoJSON 和 TopoJSON

你可以使用 GeoJSON 或 TopoJSON 在 GitHub 仓库的 README 文件或 GitHub Wiki 中添加交互式地图。

你可以使用代码块语法添加交互式地图。

  1. GeoJSON 可以通过指定坐标来创建地图。要添加交互式地图,请使用以下语法:geojson 你的代码
  2. TopoJSON 可以通过指定坐标和形状来创建地图。要添加交互式地图,请使用以下语法:topojson 你的代码

使用 GeoJSON 的示例:

```geojson
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "properties": {
        "ID": 0
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
              [-90,35],
              [-90,30],
              [-85,30],
              [-85,35],
              [-90,35]
          ]
        ]
      }
    }
  ]
}
```

在 markdown 中创建 geojson

TopJSON 的示例:

```topojson
{
  "type": "Topology",
  "transform": {
    "scale": [0.0005000500050005, 0.00010001000100010001],
    "translate": [100, 0]
  },
  "objects": {
    "example": {
      "type": "GeometryCollection",
      "geometries": [
        {
          "type": "Point",
          "properties": {"prop0": "value0"},
          "coordinates": [4000, 5000]
        },
        {
          "type": "LineString",
          "properties": {"prop0": "value0", "prop1": 0},
          "arcs": [0]
        },
        {
          "type": "Polygon",
          "properties": {"prop0": "value0",
            "prop1": {"this": "that"}
          },
          "arcs": [[1]]
        }
      ]
    }
  },
  "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]]
}
```

在 markdown 中创建一个 TopJson

ASCII STL

GitHub Flavored Markdown 支持 STL 语法。STL 语法允许你在 markdown 中添加交互式 3D 模型。你可以使用以下语法:stl 你的代码.

```stl
solid cube_corner
  facet normal 0.0 -1.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 1.0 0.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
  facet normal 0.0 0.0 -1.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 1.0 0.0 0.0
    endloop
  endfacet
  facet normal -1.0 0.0 0.0
    outer loop
      vertex 0.0 0.0 0.0
      vertex 0.0 0.0 1.0
      vertex 0.0 1.0 0.0
    endloop
  endfacet
  facet normal 0.577 0.577 0.577
    outer loop
      vertex 1.0 0.0 0.0
      vertex 0.0 1.0 0.0
      vertex 0.0 0.0 1.0
    endloop
  endfacet
endsolid
```

在 markdown 中创建一个 ASCII STL

在浏览器中,STL 语法看起来像这样:

Markdown 中的 STL 示例。

数学表达式

你可以向 GitHub markdown 文件中添加数学表达式,比如方程、术语、公式等。GitHub 使用 LaTeX 格式嵌入在 Markdown 中。有两种方法可以添加这些表达式:

  1. 写内联数学表达式
  2. 将数学表达式写成代码块

写内联数学表达式

内联数学表达式以 $ 开头,以 $ 结尾。

内联数学表达式示例:$\sqrt{3x-1}+(1+x)^2$

内联数学表达式示例

在浏览器中,内联数学语法看起来像这样:

内联数学表达式示例

将数学表达式写成代码块

要将数学表达式的代码块添加到 Markdown 文件中,请使用 ```math 代码块,并用 ````` 反引号将其包裹起来,以将表达式显示为块。

要将数学表达式的代码块添加到 Markdown 文件中,请使用 ````math 代码块,并用三个反引号将其包裹起来,以将表达式显示为块。

```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
```

代码块数学表达式示例

在浏览器中,数学代码块语法看起来像这样:

代码块数学表达式示例

结论

Markdown 语法在 GitHub 和其他所有中心 Git 服务器(如 GitLab、Gitea 等)中都可以很好地工作。

不同的工具对它们的 markdown 命名方式不同。例如,GitHub 以自己的方式扩展了 markdown 的功能,并构建了 GitHub Flavored Markdown。GitLab 也扩展了 markdown 的功能,并构建和创建了 GitLab-flavored markdown。

Markdown 语法在每个 Git 服务中大多是相同的。但是警告、图表和其他一些功能只在 GitHub Flavored Markdown 中有效。

(本文视频讲解:java567.com)

相关推荐

一篇文章认识JavaScript中的Web API

在了解webapi之前先要明白在我们声明变量三个关键字(var、let、const),我们到底该用哪一个?首先排除var,它是老牌的写法,会有很多问题,可以淘汰掉...我们在开发中建议const...

html5大神结合js带你研究古老读心术,你的心思早被猜透

javascript/HTML5课题:javascript开发读心术游戏PS:大爆料!javascript解密读心术游戏背后故事知识点:读心术原理算法独家揭秘,HTML5最新选择器,...

纯CSS实现3个圆圈横向排列不断闪烁的Loading特效

这个纯CSS实现的Loading特效是一个非常简单而实用的选择,它由三个圆圈横向排列,并不断闪烁。这种动画效果很适合用于页面加载过程中,为用户提供一个愉悦的等待体验。在这个特效的设计中,使用了CSS的...

网站建设知识分享系列文章三:符合用户体验的网页设计应如何做?

上篇文章向各位讲述了网站建设知识分享系列文章二:如何选择建站公司,今天我们来讲述下建站公司选定后,网站制作流程是怎样的,有哪些需要注意的细节性问题。选定建站公司,签订正规劳务合同后,最先开始的是设计环...

「更新」微信小程序 Lottie 动画组件 lottiejs-miniapp V1.1.0 发布

lottiejs-miniapp当前版本号:1.1.0npm地址:...

Web开发基础之jQuery javascript web开发

jQuery是一个JavaScript库。jQuery极大地简化了JavaScript编程。jQuery的语法设计可以使开发更加便捷,例如操作文档对象、选择DOM元素、制作动画效果、事件处理、使用Aj...

Web前端:JavaScript最强总结,最全面的零基础入门教程

JavaScript是网景(Netscape)公司开发的一种基于客户端浏览器、面向(基于)对象、事件驱动式的网页脚本语言。JavaScript语言的前身叫作Livescript。JavaScript...

jQuery 动画制作与特效 jquery的动画函数

使用show()和hide()方法在普通的javascript编程中,要实现元素的显示、隐藏通常是利用其CSS的display属性或者visibility属性。在jQuery中提供了show()和hi...

JavaScript+css实现的登录注册页面web前端html源码

大家好,今天给大家介绍一款,JavaScript+css实现的登录注册页面web前端html源码(图1),布局合理。送给大家哦,获取方式在本文末尾。文本框获取焦点动画特效(图2)源码完整,需要的朋友可...

CSS 3.0+HTML5.0制作各种网页特效

?1、C33实现点击图片渐渐放大特效??2、CSS3实现图片全屏背景特效?3、CSS3实现的鼠标移动到图片上不规则放大??3、jQuery+CSS3模拟苹果桌面系统??4、CSS3+jQuery照片...

js+css实现的按钮悬停动画特效html前端源码,随机元素弹出效果

大家好,今天给大家介绍一款,js+css实现的按钮悬停动画特效html页面前端源码,随机元素弹出(图1)。送给大家哦,获取方式在本文末尾。鼠标经过按钮区域的时候,会随机从不同位置上弹出很多小元素,效果...

Swiper - 免费开源、功能强大的触摸滑动js特效插件

简单配置就能实现手机、PC网页中滑动、焦点轮播图、tab切换和触摸导航等大部分功能。js滑动特效插件Swiper是一款纯javascript打造的滑动特效插件,主要用对移动端web开发...

html5精选特效代码分享(收藏) html酷炫特效

在网页设计过程中,我们会经常用到一些HTML5特效代码,下面就是为大家整理分享的一些好看炫酷且实用的HTML5特效代码,可以放心在您的应用程序中使用。一、Canvas跟随鼠标光标动画特效演示、下载地址...

玩转Markdown(2)——抽象语法树的提取与操纵

上一篇玩转Markdown——数据的分离存储与组件的原生渲染发布,转眼已经鸽了大半年了。最近在操纵mdast生成md文件的时候,心血来潮,把玩转Markdown(2)给补上了。...

任由文字肆意流淌,更自由的开源 Markdown 编辑器

对于创作平台来说内容编辑器是十分重要的功能,强大的编辑器可以让创作者专注于创作“笔”下生花。而最好取悦程序员创作者的方法之一就是支持Markdown写作,因为大多数程序员都是用Markdown...

取消回复欢迎 发表评论: