Skip to content

开源贡献文档格式说明

Jump to bottom
Frank edited this page Dec 27, 2018 · 15 revisions

项目目录

这里我将详细罗列一些开源贡献过程中会用到的目录，未说明的目录不必理会，我会逐步清理。

├── assets                     // 根目录图片文件夹
├── course                     // 学习课程相关目录
├── others                     // 其他一些老文件，杂七杂八的东西，待整理
├── notes                      // 文档目录
│   ├── Frontend               // ★ 前端部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── MachineLearning        // ★ 机器学习部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── DeepLearning           // ★ 深度学习部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── DistributedSystem      // ★ 分布式系统部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── JavaArchitecture       // ★ Java核心部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── JavaWeb                // ★ Java web框架部分
│   ├── ├── assets             // 当前目录：图片文件夹
│   ├── ├── xx1.md             // 当前目录：文章 xx1
│   ├── ├── xx2.md             // 当前目录：文章 xx2
│
│   ├── archives               // ★ 文章部分
│
│   ├── docs                   // ★ 本仓库文档部分
│
│   ├── assets                 // ★ notes下文章图片位置（以后图片都放在这下面）
│   ├── pics                   // ★ notes下文章图片位置（老的目录）
│
│   ├── xx1.md                 // notes目录下的文章 xx1
│   ├── xx2.md                 // notes目录下的文章 xx2
│
├── README.md                  // 仓库主页（索引目录入口，技能清单）

格式要求

图片格式

  1. 图片文件夹统一 assets 命名规则，在仓库中请不要引用网络上的 URL ，请直接将图片下载至本仓库，以防止外链失效后图片无法预览。

  2. 图片预览请不要使用如下的 markdown 语法，如下的图片标签在 GitHub 展示中会左对齐，影响阅读体验。（除非有强烈的左对齐需求，否则不建议使用）

    ![this is a pic](assets/fullstack-tutorial.png)

    应使用如下的图片引用方式，可实现图片居中效果（这里注意，图片的目录尽量同级别，不要使用上级或者下级目录，即 src 引用为：assets/hello-world.png）

    // 居中换行
<div align="center"><img src="assets/hash-to-badlink.png" width=""/></div><br/>

// 居中不换行
<div align="center"><img src="" width=""/></div>

段首空格

　　这里开始是我的正文内容（在本行前面的空行），其实这个段首空行其实可以根据文章样式自行决定，不是必要的。

软件环境

文字编写

建议使用 Typora 软件进行编写，此软件的功能强大，可以实现工程化的目录结构，像写项目代码一般的写作感知。本软件主要有如下几大优势：

  1. 所见即所得，免除了面对 markdown 源码的不友好

  2. 在复制网络上图片（或是复制截图的图片）的时候，可以自动的将网络上的图片下载到 ./assets 目录（若不存在文件夹则可以直接复制），提高了对于图片引用的效率

1543553039413

软件下载：Typora — a markdown editor, markdown reader.

截图工具

推荐使用百度输入法的截图工具啦，可以截图后的图片复制到 Typora 中后，默认图片的命名将是一个类似时间戳的命名。请不要使用 QQ 输入法啦，会出现 QQ 截图 的字样。

当然啦，这个不是重点，不一定要用，只要能够完整的命名图片不产生冲突更好呢。

绘图工具

  • Visio：微软绘图工具，以直观的方式工作，轻松绘制图表
  • 亿图：国产综合图形图表设计软件。类似 visio 的绘图工具
  • ProcessOn：支持流程图、思维导图、原型图、UML、网络拓扑图、组织结构图等
  • draw.io：free online diagram software for making flowcharts, process diagrams, org charts, UML, ER and network diagrams

思维导图与原型设计

  • XMind：思维导图，框架图等等，非常推荐。收费软件，部分功能可用
  • MindManager：让思考、计划和沟通变得更容易
  • 百度脑图：在线免费脑图，推荐
  • Mockplus：更快、更简单的原型设计
  • Axure RP：是一款专业的快速原型设计工具

TOC 目录生成

推荐使用 vscode 插件：Markdown TOC 1.56

1543553229015

1543553376968

在最新的vscode markdown toc插件中可能会遇到下面的问题，可以参考如下的 issue

"auto" inserted instead of line breaks in TOC · Issue #65 · AlanWalk/markdown-toc

https://github.com/AlanWalk/markdown-toc/issues/65

当然如果你不想用 vscode，还有一个 pandoc 或许可以帮助到你，这里有一份文档：pandoc | 如何为 Markdown 文件自动生成目录？ - 简书

pandoc -s --toc FAQ.md -o FAQ.md

版本控制工具客户端

  • sourceTree（真的别用 git bash 或者命令行啦，对于图片的管理真的很不方便）

    当然，这不重要，怎么方便怎么来

其他资源

Full Stack Developer Tutorial，后台技术栈/全栈开发/架构师之路，秋招/春招/校招/面试。 from zero to hero.

⊱ 开源小组，英雄招募令

Clone this wiki locally