[TOC] #### 1. 介紹 --- README.md:項目的自述文件,用于介紹項目整體的一個概覽 README.md 一般出現(xiàn)在 git 倉庫的根目錄下,作用是對項目的主要信息進行描述 如果一個項目很長時間沒有修改了,突然你需要修改這個項目,通過查看 README.md 對項目的描述可以讓你快速上手,當別人接手你的項目或你接手別人的項目也能快速的了解該項目 #### 2. 規(guī)范 --- 對于剛接手項目的陌生人,應該通過 README.md 快速獲取到項目內容的要點,因此其內容應該是項目整體的一個概覽。其實這個文件內容有約定俗成的規(guī)范,這個規(guī)范也是眾多開源開發(fā)者相互磨合形成的。文件內容理應圍繞下面內容編寫: 1. 項目介紹 2. 運行環(huán)境要求 3. 依賴的第三方插件 4. 部署要素,操作說明 5. 代碼結構說明(目錄結構) 6. 開發(fā)環(huán)境,測試環(huán)境,正式環(huán)境域名等參數(shù)說明 README.md 內容結構公認比較漂亮的一種是 `logo + 徽章 + 正文`,Vue 倉庫就是如此:<https://github.com/vuejs/vue> ![](https://img.itqaq.com/art/content/7ef8cca2c773f363b9bf2b75ea22ed8d.png) 很多非開源項目并不會專門設計自述文件的 logo,將 logo 換為項目名稱也是挺好看的,如下所示: ![](https://img.itqaq.com/art/content/28964e25abc846c04df8104ca73acfb4.png) 自述文件中對于標題的選用: + 項目名稱使用一級標題 + 項目介紹使用二級標題,項目介紹下面的內容使用三級標題,依次類推 #### 3. 徽章 --- 人活一張臉,樹活一張皮,git 倉庫也不例外,好看的倉庫從 README 開始,而好看的 README 從置頂?shù)男』照麻_始 置頂徽章生成網站:<https://shields.io/#your-badge> 輸入想要的標簽文字和顏色,就可以得到一個最簡單的個性徽章 使用查詢字符串參數(shù) style 可以自定義徽章樣式: + flat 扁平化,默認效果 + flat-square 扁平化+去圓角 + for-the-badge 扁平化+去圓角+放大 + social 社交樣式 + plastic 立體效果 ``` https://img.shields.io/badge/Node-12.18.2-yellowgreen?style=plastic ``` #### 4. 模板 --- 居中的項目 logo: Markdown 支持內嵌 HTML 代碼,將下面代碼直接放于 README.md 中即可 ```html <p align="center"> <a href="https://vuejs.org" target="_blank"> <img width="100" src="https://vuejs.org/images/logo.png"> </a> </p> ``` 居中的項目名稱: ```html <h1 align="center">康盈養(yǎng)老PC管理后臺</h1> ``` 項目名稱下面一般都是放置漂亮的徽章: ```html <p align="center"> <img src="https://img.shields.io/badge/PHP-7.3-green" /> <img src="https://img.shields.io/badge/MySQL-5.7-green" /> <img src="https://img.shields.io/badge/Node.js-12.18.2-green" /> </p> ``` 自述文件的正文: ``` ## 運行環(huán)境 --- | 環(huán)境 | 接口域名 | 后臺域名 | | --- | --- | --- | | 本地環(huán)境 | http://192.168.1.183 | xxx | | 測試環(huán)境 | http://test.itqaq.com | xxx | | 正式環(huán)境 | http://m.waterflosserreview.com | xxx | ``` #### 5. 示例 --- ```markdown <p align="center"> <a href="https://vuejs.org" target="_blank"> <img width="100" src="https://vuejs.org/images/logo.png"> </a> </p> <h1 align="center">康盈養(yǎng)老PC管理后臺</h1> <p align="center" style="margin-bottom:16px;"> <img src="https://img.shields.io/badge/PHP-7.3-green" /> <img src="https://img.shields.io/badge/MySQL-5.7-red" /> <img src="https://img.shields.io/badge/Node.js-12.18.2-green" /> </p> <p align="center"> Vue3 組件庫,Typescirpt 編寫,高性能,支持按需引入、國際化、可配置主題。 </p> ## 項目介紹 --- ## 依賴插件 --- | 插件名稱 | 插件官網 | | --- | --- | | z-paging | https://z-paging.zxlee.cn | | uview-ui | https://www.uviewui.com | ## 項目部署 --- ## 環(huán)境說明 --- | 環(huán)境 | 接口域名 | 后臺域名 | | --- | --- | --- | | 測試環(huán)境 | `https://test.itqaq.com` | https://api.itqaq.com | | 正式環(huán)境 | `https://blog.itqaq.com` | https://api.itqaq.com | ```