{"id":20089038,"url":"https://github.com/taseikyo/markdown-guide","last_synced_at":"2025-09-07T04:35:04.929Z","repository":{"id":101792007,"uuid":"290768398","full_name":"taseikyo/markdown-guide","owner":"taseikyo","description":"中英文混排的 Markdown 写作指南","archived":false,"fork":false,"pushed_at":"2020-12-18T01:27:17.000Z","size":1077,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-03T14:11:06.054Z","etag":null,"topics":["markdown","markdown-guide"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taseikyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-27T12:23:46.000Z","updated_at":"2024-08-20T07:26:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"08ca063a-1c31-4b4c-ac4f-66dc06daceed","html_url":"https://github.com/taseikyo/markdown-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/taseikyo/markdown-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taseikyo%2Fmarkdown-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taseikyo%2Fmarkdown-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taseikyo%2Fmarkdown-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taseikyo%2Fmarkdown-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taseikyo","download_url":"https://codeload.github.com/taseikyo/markdown-guide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taseikyo%2Fmarkdown-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273997054,"owners_count":25204473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","markdown-guide"],"created_at":"2024-11-13T16:16:10.587Z","updated_at":"2025-09-07T04:35:04.921Z","avatar_url":"https://github.com/taseikyo.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"images/header-cat.jpg\" alt=\"Markdown Guide\" title=\"Markdown Guide\"\u003e\n\u003c/p\u003e\n\n注意：这只是我以个人习惯写成的一份 Markdown（下面写作 md）指南，毕竟每个人的习惯不同，如果不喜欢或者觉得是篇辣鸡指南可以无视。\n\n## Table of Contents\n- [写在前面的话](#写在前面的话)\n- [文件名](#文件名)\n- [目录](#目录)\n- [标题](#标题)\n- [正文](#正文)\n- [图片](#图片)\n- [列表](#列表)\n- [代码](#代码)\n- [超链接](#超链接)\n- [表格](#表格)\n- [公式](#公式)\n- [图表题注与文件路径](#图表题注与文件路径)\n- [参考](#参考)\n\n## 写在前面的话\n\n写这篇所谓的指南目的是强制自己去执行一个所谓的标准，因为有时候自己觉得一种写法很棒，应该作为标准，之后就忘记了（鱼的记忆），所以记下来可供查询。\n\n早就想写一份属于自己的 md 写作指南了，一直拖拖拉拉没写（懒），自从接触 md（应该是大三暑假实习，在实验室第一次接触到）之后就放弃了其他的记笔记文档格式（txt or docx），为啥？因为 md 它有多种格式（相比 txt），语法简单，轻量级（相比 docx），所见即所得，我习惯是用 Chrome + Markdown Preview Plus 看 md 文档。\n\n中英文应该自觉加上空格，网上也有大量格式化的工具或者网站，复制粘贴就可以得到一份空格分隔后的文档，如果懒得找，我这里有一个小工具：[pangu](https://github.com/taseikyo/PyQt5-Apps#pangu)，它是基于 [pangu.py](https://github.com/vinta/pangu.py) 用 PyQt 套了个壳子的小工具。\n\n最后推荐自己写的一个 Sublime Text 的一个插件：[sublime-markdown-helper](https://github.com/taseikyo/sublime-markdown-helper)。该插件可以加速 md 文档的书写（大概），基本是常用的几个样式，所有格式都需要全段落选择，效果如下所示：\n\n![md-helper](images/sublime-markdown-helper.gif \"sublime-markdown-helper\")\n\n## 文件名\n\n1. 文件名不应该出现空格，如果需要请使用连字符（\"-\"）连接。\n\n```\nmarkdown guide.md ×\nmarkdown-guide.md √\n```\n\n2. 如果出现中英文怎么办？参考上面规定：使用连字符连接。\n\n```\npython使用指南.pdf  ×\npython 使用指南.pdf ×\npython-使用指南.pdf √\n```\n\n3. 文件名中的英文字母应该都为小写字母，无论是否为专有单词，就像上面的一个示例。\n\n## 目录\n\n每篇 md 文档都应该有一个目录，方便跳转，同时也方便有个对整个文档的全局了解。为此我还自己写了一个 [Python 脚本](https://github.com/taseikyo/backup-utils/blob/master/Python/006_auto_generate_toc.py) 来自动生成目录，因为是直接计算开头的井号数（\"#\"），可能有些 bug 或者格式问题，最终需要自己手动微调一下。\n\n## 标题\n\n1. 标题也应遵循中英文加空格的规定。\n\n```\n# title标题 ×\n# title 标题 √\n```\n\n2. 标题跟其他格式之间应该加一个空行，这里其他格式是指任何格式，标题、正文或者段落等等。\n\n错误示范：\n\n```\n# title1\n## title2\n\n# title1\nsentence\n\n# title1\n- p1\n- p2\n```\n\n正确示范：\n\n```\n# title1\n\n## title2\n\n# title1\n\nsentence\n\n# title1\n\n- p1\n- p2\n```\n\n3. 关于标题格式，请使用井号（\"#\"），而不要使用等于号（\"=\"）或者连字符（\"-\"）\n\n错误示范：\n\n```\n标题标题标题\n=================\n```\n\n正确示范：\n\n```\n# 标题标题标题\n```\n\n4. 标题最多应使用到三级，因为对于四级及以上渲染出来字体比正文还小，已经不太好看了。\n\n## 正文\n\n1. 中英文之间加空格是必须的。\n\n2. 段落换行多加一个空行（回车），如果只有一个回车，有些网站（GitHub）仍然会渲染成一个段落。\n\n错误示范：\n\n```\nsentence1\nsentence2\n```\n\n正确示范：\n\n```\nsentence1\n\nsentence2\n```\n\n3. 正文与列表之间要加空行。\n\n错误示范：\n\n```\nsentence\n- p1\n- p2\n```\n\n正确示范：\n\n```\nsentence\n\n- p1\n- p2\n```\n\n## 图片\n\n1. 不要添加自身链接\n\n没有必要的链接不要加，这一点跟参考自跳转类似，白痴的写法。\n\n错误示范：\n\n```\n[![](xxx.jpg)](xxx.jpg)\n```\n\n正确示范：\n\n```\n![](xxx.jpg)\n```\n\n## 列表\n\n1. 无序列表应使用连字符（\"-\"）而不是使用星形符号（\"\\*\"）\n2. 列表嵌套不需要多加一个空行。\n\n错误示例：\n\n```\n- aaa\n\n\t1. xxx\n\t2. yyy\n```\n\n正确示例：\n\n```\n- aaa\n\t1. xxx\n\t2. yyy\n```\n\n## 代码\n\n1. 应尽量标记语言类型。\n2. 与其他格式之间加空行。\n3. 行内代码前后加空格。\n4. 代码请格式化，否则会挺难看的。\n\n## 超链接\n\n对于是超链接的关键词前后应该加空格。\n\n```\nasda[GitHub](github.com)asdasd    ×\nasda [GitHub](github.com) asdasd  √\n```\n\n## 表格\n\n表格最好美观（如保持连字符的长度一致），推荐 [Tables Generator](https://www.tablesgenerator.com/markdown_tables) 自动生成，不用自己敲。\n\n## 公式\n\n在 md 文档中插入 LaTeX 公式可太常见了，然而 GitHub 并不支持，有其他方法可以间接达到效果，比如用 CodeCogs 的外链。但我习惯之间在正文中直接插入公式了，毕竟 Markdown Preview Plus 是支持的。\n\n关于公式的生成，有很多网站提供有这类功能，比如之前有 UP 主做了个 [LaTeX 公式编辑器](https://latexlive.com/) 的网站，还支持图片识别，准确率还挺高的，所以我基本图片直接拖过去了。\n\n## 图表题注与文件路径\n\n写 md 会经常需要插入图片跟表格，以及代码，有时候可能需要插入题注，所以这里也做一个规定（参考 Word）。\n\n- 图片题注，使用斜体并在文字前加一个星号（\"\\*\"），文字在图片下方：\n\n![](https://avatars3.githubusercontent.com/u/23132915?s=460\u0026u=6aed8d3229553ec6e00d1f8a684df0cd4d4a9abd\u0026v=4)\n\n\\**taseikyo's avatar (a smart boy :3)*\n\n- 表格题注与代码文件路径，使用引用格式，并放在表格/代码的上方：\n\n\u003e codes/hello.c\n\n```C\n#include \u003cstdio.h\u003e\n\nint main(int argc, char* argv[]) {\n    printf(\"hello world\\n\");\n    return 0;\n}\n```\n\n\u003e taseikyo'info\n\n|    name    |     languages    |    skills   |\n|:----------:|:----------------:|:-----------:|\n| Lewis Tian | Chinese, English | C++, Python |\n\n## 参考\n\n1. 不要使用链接的写法\n\n下面这种写法真的蠢，直接给出链接不就完了，再套一层完全没必要。\n\n错误示范：\n\n```\n### 参考\n\n- [https://github.com/taseikyo/markdown-guide](https://github.com/taseikyo/markdown-guide)\n```\n\n正确示范：\n\n```\n### 参考\n\n- https://github.com/taseikyo/markdown-guide\n```\n\n## LICENSE\n\nCopyright (c) 2020 Lewis Tian. Licensed under the MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaseikyo%2Fmarkdown-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaseikyo%2Fmarkdown-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaseikyo%2Fmarkdown-guide/lists"}