DuangDuangDuang!码云项目的 Readme.md 特殊技能

服务器

浏览数:68

2020-6-22

我们在 码云 上创建新项目的时候,常常会看到默认使用 README 文件初始化该项目(如图1 所示),然后在新建项目的根目录下就会生成一个 README.md 文件(如图2 所示)。

图1 默认选中 README

图2 生成 README 文件

那究竟什么是 README ?它有什么特殊的功能?我们要如何操作才能写出一个漂亮的 README 呢?

##一、什么是 README.md 文件 ?

一个合格的老司机想要在 码云 上了解一个项目,首先都会去翻看该项目的 README 文件,因为这个小小的静态文件其实传达了整个项目的概述,如项目的介绍、代码实现的功能、系统环境参数、部署要素等。

README 文件后缀名为 md,当然扩展名也可能是 txt ,rb 等。md 是 markdown 的缩写,是一种轻量级的「标记语言」。它用「标记」语法,来代替常见的字处理软件中大量的排版格式,从而让大家能够更专注于文字内容,是适合所有人的写作语言。

大家可以通过以下链接来进一步学习 markdown 的写作:

Markdown 语法说明

Markdown 在线工具

##二、如何玩转 码云 项目的 README.md?

码云 上创建 README.md 文件的时候,有一个关于文件内容显示优先级的小窍门分享给大家。

在如图2 所示的根目录下,再创建一个新文件 README.osc.md(或者 README-osc.md 或者 README_osc.md),大家会发现虽然在根目录下同时存在两个 README 文件,但项目页会优先显示含有 osc 的 README 文件中的内容。

图3 README.md 文件中的内容

图4 README.osc.md 文件中的内容

图5 优先显示README.osc.md 内容

除此之外,当我们使用不同语言创建 README.md 文件时,系统会根据不同的命名规范来判断其显示的优先级,如下所示(优先级从左到右):

  • zh-CN 简体时:zh,cn,zh-cn,zh_cn;

  • zh-TW 繁体时:zh-hk,zh-tw,zh-yue,zh_hk,zh_tw,zh_yue;

  • en 英文时:en;

##三、README.md 常规模板

如果 README 包括下面的内容,那么当使用者打开项目,浏览 README 后,基本就知道该如何下手了。

  • 项目简介
  • 功能特性
  • 环境依赖
  • 部署步骤
  • 目录结构描述
  • 版本内容更新
  • 声明
  • 协议

当然这不是一个绝对的模板,但是其中有些必要的元素(如项目的介绍,使用,部署及目录结构)还是需要列出来。

如果你也了解 码云 项目 README 的小窍门,欢迎留言勾搭,分享。如果你还没有使用过 码云 的话,也欢迎来试试手~

作者:码云Gitee