diff --git a/01.md b/01.md new file mode 100644 index 0000000000000000000000000000000000000000..4070419f3d366d2bc5f87073fe3885a5e4a7e063 --- /dev/null +++ b/01.md @@ -0,0 +1,62 @@ +## 一、 Markdown 入门 +------ + +### 1. 认识 Markdown + +##### 什么是 Markdown ？ +* Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。 +* Markdown 语言在 2004 由约翰·格鲁伯（英语：John Gruber）创建。 +* Markdown 编写的文档可以导出 HTML 、Word、图像、PDF、Epub 等多种格式的文档。 +* Markdown 编写的文档后缀为`.md, `.`markdown`。 + +##### Markdown 应用在哪里 ？ +Markdown 可以用来撰写电子书，如：Gitbook；可以用来写博客、邮件。 + +当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如：GitHub、简书、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge等。 + +##### 为什么使用 Markdown ？ +简单的说， Markdown 用简洁的语法代替排版，而不像一般我们用的文字处理软件如Word或Pages有大量的排版和字体设置。 + +Markdown 很容易转化成 HTML 或者 PDF +git 的` README.md` 就是 Markdown 格式的。 +例如： 和 + +### 2. Markdown 基础语法 + +##### 标题 + 在想要设置为标题的文字前面加#来表示 +一个#是一级标题，二个#是二级标题，以此类推。支持六级标题。 + + **注：** 标准语法一般在#后跟个空格再写文字 +示例： + +![](img/1-2-1.png) + +效果如下： +# 这是一级标题 +## 这是二级标题 +### 这是三级标题 +#### 这是四级标题 +##### 这是五级标题 +###### 这是六级标题 + +##### 字体 +* 加粗 +要加粗的文字左右分别用两个*号包起来 +* 斜体 +要倾斜的文字左右分别用一个*号包起来 +* 斜体加粗 +要倾斜和加粗的文字左右分别用三个*号包起来 +* 删除线 +要加删除线的文字左右分别用两个~~号包起来 +示例：
+![](img/1-2-2.png) +
+效果如下： +**这是加粗的文字** +*这是倾斜的文字* +***这是斜体加粗的文字*** +~~这是删除线的文字~~ + + **注：** 如果要在文字前后直接插入普通的星号或底线，你可以用反斜线（转义符）： +\*this text is surrounded by literal asterisks\* diff --git a/02.md b/02.md new file mode 100644 index 0000000000000000000000000000000000000000..a64b2203eaf7d8f51ea3212262c47fd31bb8b913 --- /dev/null +++ b/02.md @@ -0,0 +1,33 @@ +## 二、 Markdown 文档的撰写 +------ + +### 1. Markdown编辑器分类 + +按照Markdown编辑器的使用环境，可以将它们归纳为三类。 + +* 平台集成工具：各大在线博客、社区平台自带的写作工具，比如CSDN、博客园、简书等。 +* 独立软件类：下载到自己机器上使用的独立产品，可以编辑本地文件，比如Mou、MarkdownEditor、Haroopad等。 +* 插件类：它本身是不能独立使用的，可以在你现有的主流编辑器安装，使你现有的编辑器具有Markdown的功能，比如Atom、WebStorm、Sublime Text等。 + +实际上，任何编辑器都可以使用Markdown语法进行文档撰写(写完之后再转换成你需要的格式就可以)，但是为了**预览和保存**的方便，使用Markdown编辑器会使办公更加高效与便捷。 + +### 2. 在线编辑器 +* [MdEditor](http://jbt.github.io/markdown-editor/) +是一个在线编辑Markdown文档的编辑器，扩展了Markdown的功能（如表格、脚注、内嵌HTML等等），以使让Markdown转换成更多的格式，和更丰富的展示效果，这些功能原初的Markdown尚不具备。 +MarkdownEditor还有拼写检查功能。 +具有可视化预览面板，你可以预览Markdown格式。可以将编辑的文本保存为`.md`格式。
+![Alt text](img/2-2-1.png) + +* 插件的使用:[在浏览器里添加Markdown Here(插件)](https://github.com/adam-p/markdown-here) +添加这个插件的作用是在网页一些文本编辑的地方, 使用Markdown编辑文本。
具体操作方法可以参考Atom插件的下载与使用 + + +### 3. 离线编辑器 +* [MarkdownPad](http://markdownpad.com/) +MarkdownPad是**独立的软件**。 +主要特点是：左右分屏实时预览、可自定义添加各种CSS样式渲染。是windows下较好用的Markdown编辑器之一，不过仅支持windows。它有免费版和收费版（MarkdownPad Pro），一般情况下免费版就够用了。 + +MarkdownPad支持键盘快捷键和工具栏操作，即可添加标记也可移除，支持即时HTML预览、支持自定义配色方案、字体、大小和布局、支持音乐视频，可以导出HTML和PDF。
+![Alt text](img/2-3-1.png) + + diff --git a/03.md b/03.md new file mode 100644 index 0000000000000000000000000000000000000000..63e89cedb1057231b79d0dbef36ec939fb436b8c --- /dev/null +++ b/03.md @@ -0,0 +1,60 @@ +## 三、 Markdown 进阶语法 +------ + +### 1. 链接 + +##### 超链接 +* 语法说明： +[ ]里写链接文字 +( )里写链接地址 +( )中的“ ”中可以为链接指定title属性，title属性**可加可不加**。title属性的效果是鼠标悬停在链接上会出现指定的 title文字，链接地址与title前有一个空格。 +* 例如:
![Alt text](img/3-1-1.png) + + **注：** 要在英文状态下输入！ +* 效果如下： +这是一个链接：[链接文字](https://gitee.com/ "码云") +##### 自动链接 +除了上面的超链接方式，Markdown 还支持以比较简短的自动链接形式来处理网址和电子邮件信箱。 +* 语法说明： +用**尖括号**包起来， Markdown 就会自动把它转成链接。 +* 例如：
![Alt text](img/3-1-2.png) + +**注：** 要在英文状态下输入！ +* 效果如下： + + +### 2. 图片 +* 语法说明： +开头一个感叹号 ! +接着一个方括号，里面放上图片的替代文字 +接着一个普通括号，里面放上图片的网址或本地路径（可以是*相对路径*或*绝对路径*，**详见第六章说明**） +最后还可以用引号包住并加上选择性的 'title' 属性的文字。 +* 例如:
+![Alt text](img/3-2-1.png) + + **注：** 要在英文状态下输入！ +* 效果如下： +![码云](img/3-2-1.jpg "码云网站") + +### 3. 表格 +* 语法说明： +Markdown 制作表格使用 `| `来分隔不同的单元格，使用` -` 来分隔表头和其他行。 +同时，我们可以设置表格的对齐方式： +-: 设置内容和标题栏居右对齐。 +:- 设置内容和标题栏居左对齐。 +:-: 设置内容和标题栏居中对齐。 +* 例如:
+![Alt text](img/3-3-1.png) +
**注:**` -`的多少无所谓，`| `的输入方法为 按住`shift+\` +* 效果如下： + +|左对齐|居中对齐|右对齐| +|:---|:--:|-:| +|单|单元格|格| +|单|单元格|格| + + +### 4. 更多学习资源 +* [Markdown语法及原理从入门到高级](https://blog.csdn.net/weixin_35073408/article/details/100586583?utm_source=app) +* [Markdown 免费编辑器](http://www.markdown.cn/#editor) +* [码云的 Markdown 解析器 **CommonMark** 语法文档](http://commonmark.org/help/) \ No newline at end of file diff --git a/04.md b/04.md new file mode 100644 index 0000000000000000000000000000000000000000..f1d625d9c8931e14d852daa2a5cc32f8009d7890 --- /dev/null +++ b/04.md @@ -0,0 +1,79 @@ +## 四、让 Markdown 文档更美观 +------ + +### 1. 如何更美观的基本思路 +  上几章介绍得语法已经能满足基本文档编写的需求，但有时候还想要文档看起来更美观一些，这时候需要一些用于排版的进阶语法，实际上，这里用的就是**HTML**的标记来实现了。 +* 标题与正文之间需要一条分割线。用法是另起一行，连续输入三个星号`***`或减号`---` +或底线`___`即可。 +* 一般来说，**首行缩进**两字符让文档更加规范。 +* 我们在两个不同的文字块之间，一定要**空行**以示区分，不然就会被归入同一文字块中。 +* 中英文之间需要增加空格。 +* 默认图片居中在观感上更加舒适。 + +要让文本美观的前提是需要符合规范化的格式，详见**第五章**。 + +### 2. 段落与换行 +在编辑的时候有多少个**空行**(只要这一行只有回车或者space没有其他的字符就算空行)，在渲染之后，**只隔着一行**。 + +* **换行**的语法说明： +段落的**换行**是使用两个以上**空格加上回车**， +也可以使用 html 语言中的`
`标记，强制空行，每输入一个标签则多空一行。 +* **文字缩进**语法说明： +在需要首行缩进的时候，可以使用标记来强制空格。 +一个空格大小的表示：` ` 或`  ` +两个空格的大小表示：`  `或 ` ` +不换行空格：` ` 或`  ` + +### 3. 文字的位置 +* 文字对齐方式的语法说明： +>`

居中

` +>`

左对齐

` +> `

右对齐

` +* 效果： +

居中

+

左对齐

+

右对齐

+ +### 4. 图片的位置和大小 +利用Markdown在编写文档时插入图片是默认靠左，有些时候将图片设置为居中时可以更加的美观，这时就需要在**图片**的信息**前边**添加如下语句。 +* 图片位置的语法说明： +>`
` +>`
` +>`
` +* 效果： +>
+>
+>
+ +* 图片大小的语法说明： +如下格式，在图片地址前添加 width = “50” height = “50”，就可以设置图片的大小。也可以在后边输入百分比为多少，如 width = 20% height = 20%。 + +`
` + +### 5. 单独打开网页中的链接 +当我们在写文章时，突然发现如果写了一篇很长的文章，要是没有目录的话。阅读起来十分不便。页内跳转就能很好的解决这个问题。 +* 语法说明： +格式为`[点击跳转]` `(#jump)` +![Alt text](img/4-5-1.png) +* 效果： +* [1.语法示例](#1) +* [1.1图片](#1.1) +* [1.2换行](#1.2) +* [1.3强调](#1.3) + +### 6. 在文档中插入B站的视频 +在不同的解析器里，插入视频的方法有所区别，并且有的解析器不支持此功能。在这里主要介绍两种方法。 +* 语法说明： +格式为 +`` + +这种方法，在码云的编辑器里适用。`src`后面放的是**源文件**地址。一般来说，需要把视频文件放到本地仓库，再推送到远程仓库，最后生成`src`地址。 +* 另一种方法说明： +部分编辑器支持**嵌入代码**。以B站视频为例，在点击**分享**按钮后，会出现两种选项。选择**嵌入代码**，直接粘贴到可支持的编辑器，即可成功插入视频。 +语法说明： +` +![Alt text](./4-6-1.png)` + + diff --git a/05.md b/05.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/06.md b/06.md new file mode 100644 index 0000000000000000000000000000000000000000..de9eb0c313a02dfd3fe149376d6a0cb9db2ec250 --- /dev/null +++ b/06.md @@ -0,0 +1,46 @@ +## 六、图片使用的规范化 +------ + +### 1. 使用相对引用 +最普遍的插入图片方式有两种： +* 一种是插入**网络图片**，只需要在基础语法的括号中填入图片的网络链接即可。但缺点是：将图片存在网络服务器上，**非常依赖网络**。 +* 另一种是插入**本地图片**，只需要在基础语法的括号中填入图片的位置路径即可，支持绝对路径和相对路径。但缺点是：不灵活不好分享，本地图片的**路径更改或丢失**都会造成Markdown 文件调不出图。 + +这里，我们统一使用相对路径。方法如下： + +（1）将`.md`文件和图片放在同级目录下 + +（2）引用图片时写成如下图这种格式，就表示引用的是相对路径，当然其他路径可自行更改。以后复制文件的时候需要将图片一起打包进行传输。 + +其中*avatar*表示图片未正常加载时所显示的内容，*buildWebsites.jpg*为文件名 + +![Alt text](img/6-1-1.png) + +其子路径表示如下，其中1为文件夹名称 + +![Alt text](img/6-1-2.png) + + **注：** 在码云的仓库上传图片以后，会自动生成图片地址，如图所示。 +![Alt text](img/6-1-3.png) + +### 2. 图片的命名与保存 +* 统一格式：章—节—序号 +* 存储格式：`.PNG` + +### 3. 截图的规范 +* 截图软件：[PicPick](https://picpick.app/zh/download/)(抓取全屏幕)是一款小巧而功能全面的截图工具。软件界面模仿Windows7 画图工具的界面。picpick具备了截取全屏、活动窗口、指定区域、固定区域、手绘区域功能，支持滚动截屏，屏幕取色，调色板，放大镜，支持双显示器，具备白板、屏幕标尺、直角座标或极座标显示与测量，具备强大的图像编辑和标注功能等。 + +![Alt text](img/6-2-1.png) + +* 截图比例为1:1，并且截图要注意精准，尽量减少与表达内容无关的元素。 +* 在图片说明中，我们统一使用**矩形**和**印章**进行描述。将它们的颜色设置为：`D64305`，粗细设置为：`4px` 如下图所示。 + +![Alt text](img/6-3-1.png) + +### 4. 图片引用的统一化 +在使用picpick截图后，我们将设置图片的大小 +* 一般在网页显示的图片建议宽度最大不要超过640mm。 +* 在软件内，单击缩放按钮，勾选保持宽高比，宽度设置成小于640mm的尺寸即可。 + +下图显示为设置成宽度640mm的图片。 +![Alt text](img/6-4-1.png) diff --git a/README.en.md b/README.en.md deleted file mode 100644 index ca44e719980308c353c6cf70d79ae2b15906467f..0000000000000000000000000000000000000000 --- a/README.en.md +++ /dev/null @@ -1,36 +0,0 @@ -# 中文在线文档撰写及规范 - -#### Description -{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} - -#### Software Architecture -Software architecture description - -#### Installation - -1. xxxx -2. xxxx -3. xxxx - -#### Instructions - -1. xxxx -2. xxxx -3. xxxx - -#### Contribution - -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request - - -#### Gitee Feature - -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README.md b/README.md index 9f9d5a8a3056a5c00c91b7359f2f80b9c240d78b..ff82f941cf0cf234928bc2797a3dec8ff8d52da7 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,55 @@ -# 中文在线文档撰写及规范 +# 中文在线文档撰写及规范 -## 介绍 +---- +## 目 录 -{**以下是码云平台说明，您可以替换此简介** +### [第一章 Markdown 入门](01.md) + 1. 认识 Markdown + + 2. Markdown 基础语法 + +### [第二章 Markdown 文档的撰写](02.md) -## 目录结构 +1. 在线编辑器 +2. 离线编辑器 +### [第三章 Markdown 进阶语法](03.md) +1. 链接 +2. 图片 -#### 参与贡献 +3. 表格 + +4. 更多学习资源 + + +### [第四章 让 Markdown 文档更美观](04.md) +1. 如何更美观的基本思路 + +2. 段落与换行 + +3. 文字的位置 + +4. 图片的大小和居中 + +5. 单独打开网页的链接 + +6. 在文档中插入B站视频 + + +### [第五章 文本表述的规范化](05.md) + +### [第六章 图片使用的规范化](06.md) +1. 相对引用与绝对引用 + +2. 图片的命名与保存 + +3. 截图的规范 + +4. 图片引用的统一化 diff --git a/img/1-2-1.png b/img/1-2-1.png new file mode 100644 index 0000000000000000000000000000000000000000..b68c84f4c9bcd04e1a54184692804246dfeb94f3 Binary files /dev/null and b/img/1-2-1.png differ diff --git a/img/1-2-2.png b/img/1-2-2.png new file mode 100644 index 0000000000000000000000000000000000000000..5f962ec386399e94c59e2314c8d7628243d2decd Binary files /dev/null and b/img/1-2-2.png differ diff --git a/img/2-2-1.png b/img/2-2-1.png new file mode 100644 index 0000000000000000000000000000000000000000..7edac5cd4174e119d0e807a0cd144cff4d58182a Binary files /dev/null and b/img/2-2-1.png differ diff --git a/img/2-3-1.png b/img/2-3-1.png new file mode 100644 index 0000000000000000000000000000000000000000..fe01ccf60aba927a3cb75e70c65a6dc70541b1c1 Binary files /dev/null and b/img/2-3-1.png differ diff --git a/img/3-1-1.png b/img/3-1-1.png new file mode 100644 index 0000000000000000000000000000000000000000..b46fb9c067406b36e8d6ecdaaa80882d3517b213 Binary files /dev/null and b/img/3-1-1.png differ diff --git a/img/3-1-2.png b/img/3-1-2.png new file mode 100644 index 0000000000000000000000000000000000000000..d469ebaa8e8ef4f6488d4f5c3664b33744858f65 Binary files /dev/null and b/img/3-1-2.png differ diff --git a/img/3-2-1.jpg b/img/3-2-1.jpg new file mode 100644 index 0000000000000000000000000000000000000000..66b0fa972172d0a52ffba1b61d337e7b7a4de574 Binary files /dev/null and b/img/3-2-1.jpg differ diff --git a/img/3-2-1.png b/img/3-2-1.png new file mode 100644 index 0000000000000000000000000000000000000000..77b668ca6da3956aca3d94fad3324b1d5938e000 Binary files /dev/null and b/img/3-2-1.png differ diff --git a/img/3-3-1.png b/img/3-3-1.png new file mode 100644 index 0000000000000000000000000000000000000000..b08b1982a830e7d1715c3d8ed10624ff44de8c98 Binary files /dev/null and b/img/3-3-1.png differ diff --git a/img/4-4-1.png b/img/4-4-1.png new file mode 100644 index 0000000000000000000000000000000000000000..530053478a7537c9b18fa211985f1f9229525b1a Binary files /dev/null and b/img/4-4-1.png differ diff --git a/img/4-5-1.png b/img/4-5-1.png new file mode 100644 index 0000000000000000000000000000000000000000..0d0402a0ce12e4f37ba8f616341188e1c40cd193 Binary files /dev/null and b/img/4-5-1.png differ diff --git a/img/4-6-1.png b/img/4-6-1.png new file mode 100644 index 0000000000000000000000000000000000000000..a1702faa3174de4793890a130aa595b341c74a57 Binary files /dev/null and b/img/4-6-1.png differ diff --git a/img/6-1-1.png b/img/6-1-1.png new file mode 100644 index 0000000000000000000000000000000000000000..ca72c63951ae17d78e7f507aace093c1e6c4ac89 Binary files /dev/null and b/img/6-1-1.png differ diff --git a/img/6-1-2.png b/img/6-1-2.png new file mode 100644 index 0000000000000000000000000000000000000000..a6d8dc6854114d8da5fa30144001a8c0b79bc29d Binary files /dev/null and b/img/6-1-2.png differ diff --git a/img/6-1-3.png b/img/6-1-3.png new file mode 100644 index 0000000000000000000000000000000000000000..07bd979f4fc6be61e38e80b86b0e1afde209c5b7 Binary files /dev/null and b/img/6-1-3.png differ diff --git a/img/6-2-1.png b/img/6-2-1.png new file mode 100644 index 0000000000000000000000000000000000000000..09d371f5bbe99bb129be0296ab41bf5010c637fe Binary files /dev/null and b/img/6-2-1.png differ diff --git a/img/6-3-1.png b/img/6-3-1.png new file mode 100644 index 0000000000000000000000000000000000000000..47e5532aa58876fdbc917698c8e54e549fb8a412 Binary files /dev/null and b/img/6-3-1.png differ diff --git a/img/6-4-1.png b/img/6-4-1.png new file mode 100644 index 0000000000000000000000000000000000000000..1c041eda711e4a0e43708e2eaa1e795b6971c548 Binary files /dev/null and b/img/6-4-1.png differ