使用Markdown編寫適用於GitHub的README.md檔案的目錄結構

小白哇咔發表於2024-11-03
Github

目錄
  • 頂部
  • 1. 使用[TOC]自動生成
  • 2. VSCode中的外掛
  • 3. 手搓目錄
  • 目錄
  • 相關資料
  • 本文相關程式碼
  • 一、概述
    • 1.1 基本概念
    • 1.2 兩種處理模型
      • （1）微批處理
      • （2）持續處理
    • 1.3 Structured Streaming和Spark SQL、Spark Streaming關係
  • 二、編寫Structured Streaming程式的基本步驟
  • 三、輸入源
    • 3.1 File源
      • （1）建立程式生成JSON格式的File源測試資料
      • （2）建立程式對資料進行統計
      • （3）測試執行程式
      • （4）處理警告
      • （5）總結分析
    • 3.2 Kafka源
      • （1）啟動Kafka
      • （2）編寫生產者（Producer）程式
      • （3）安裝Python3的Kafka支援
      • （4）執行生產者程式
      • （5）編寫並執行消費者（Consumer）程式
        • 方式一
        • 方式二
      • 總結
    • 3.3 Socket源
    • 3.4 Rate源
  • surprise

頂部

1. 使用[TOC]自動生成

在文件開頭第一行單獨輸入[TOC]，Markdown編輯器就會根據文件中的標題層級自動生成目錄。在部落格園和csdn中可以透過此方法來實現自動生成目錄，但是要注意[TOC] 通常會生成文件中所有標題的目錄。如果讀者只想生成指定標題的目錄（例如，前三個標題），只能手動建立一個自定義的目錄，而不是使用自動生成的功能。
預設在GitHub中並不支援TOC的自動生成目錄

2. VSCode中的外掛

首先得有VSCode，在VSCode中下載Markdown All in One外掛後，將需要編輯的Markdown文件使用VSCode開啟進行編輯，按下萬能鍵CTRL+SHIFT+P 或 F1，輸入Markdown All in One: Create Table of Contents後回車即可
image

該外掛適用於GitHub中的Markdown的語法結構
現附上外掛GitHub連結
v3.6.2下載連結
外掛鍵盤快捷方式：
image

3. 手搓目錄

接下來介紹如何手搓適用於GitHub的Markdown的結構的目錄😎
以下為筆者的拙見，如有錯誤，請同志不吝指教
首先在編寫目錄之前請筆者明確目錄結構
可以使用無序列表來實現目錄的層級結構，之後就是建立連結錨點（每一個標題都是一個錨點），在目錄的無序列表結構中使用[回到頂部](#頂部)這樣的結構來連結到頂部標題，同理，連結到其他標題也是如此結構，如下：

語法 效果
[回到頂部](#頂部) 回到頂部

簡單總結一下在GitHub編寫README.md檔案的規律總結：

  1. 標題處理:

    • 若標題為純中文或中英文結合，無標點等特殊字元，直接用 # 加上標題名稱，例如：# 一概述 對應 [一、概述](#一概述)。

  2. 特殊符號處理:

    • 若標題中包含中文符號如 、 或 （）等標點，則在連結中忽略這些標點，例如：# （1）微批處理 對應 [（1）微批處理](#1微批處理)。

  3. 數字結構處理:

    • 對於標題中含有類似 1.1 這樣的結構，在連結中忽略 .，例如：# 1.1 基本概念 對應 [1.1 基本概念](#11-基本概念)。

  4. 空格處理:

    • 標題中的空格在連結中用 - 替代，例如：# 3.2 Kafka源 對應 [3.2 Kafka源](#32-kafka源)。

  5. 保持一致性:

    • 所有連結都採用小寫字母和連字元風格，確保在Markdown中保持一致的連結格式。

下面結合一個例項來看：

目錄

  • 相關資料
    • 本文相關程式碼
  • 一、概述
    • 1.1 基本概念
    • 1.2 兩種處理模型
      • （1）微批處理
      • （2）持續處理
    • 1.3 Structured Streaming和Spark SQL、Spark Streaming關係
  • 二、編寫Structured Streaming程式的基本步驟
  • 三、輸入源
    • 3.1 File源
      • （1）建立程式生成JSON格式的File源測試資料
      • （2）建立程式對資料進行統計
      • （3）測試執行程式
      • （4）處理警告
      • （5）總結分析
    • 3.2 Kafka源
      • （1）啟動Kafka
      • （2）編寫生產者（Producer）程式
      • （3）安裝Python3的Kafka支援
      • （4）執行生產者程式
      • （5）編寫並執行消費者（Consumer）程式
        • 方式一
        • 方式二
      • 總結
    • 3.3 Socket源
    • 3.4 Rate源

相關資料

相關資料內容

本文相關程式碼

本文相關程式碼內容

一、概述

概述內容

1.1 基本概念

基本概念內容

1.2 兩種處理模型

兩種處理模型內容

（1）微批處理

微批處理內容

（2）持續處理

持續處理內容

1.3 Structured Streaming和Spark SQL、Spark Streaming關係

Structured Streaming和Spark SQL、Spark Streaming關係內容

二、編寫Structured Streaming程式的基本步驟

編寫Structured Streaming程式的基本步驟內容

三、輸入源

輸入源內容

3.1 File源

File源內容

（1）建立程式生成JSON格式的File源測試資料

建立程式生成JSON格式的File源測試資料內容

（2）建立程式對資料進行統計

建立程式對資料進行統計內容

（3）測試執行程式

測試執行程式內容

（4）處理警告

處理警告內容

（5）總結分析

總結分析內容

3.2 Kafka源

Kafka源內容

（1）啟動Kafka

啟動Kafka內容

（2）編寫生產者（Producer）程式

編寫生產者（Producer）程式內容

（3）安裝Python3的Kafka支援

安裝Python3的Kafka支援內容

（4）執行生產者程式

執行生產者程式內容

（5）編寫並執行消費者（Consumer）程式

編寫並執行消費者（Consumer）程式內容

方式一

方式一內容

方式二

方式二內容

總結

總結內容

3.3 Socket源

Socket源內容

3.4 Rate源

Rate源內容

上述內容的markdown程式碼為：

# **目錄**
- [相關資料](#相關資料)
  - [本文相關程式碼](#本文相關程式碼)
- [一、概述](#一概述)
  - [1.1 基本概念](#11-基本概念)
  - [1.2 兩種處理模型](#12-兩種處理模型)
    - [（1）微批處理](#1微批處理)
    - [（2）持續處理](#2持續處理)
  - [1.3 Structured Streaming和Spark SQL、Spark Streaming關係](#13-structured-streaming和spark-sqlspark-streaming關係)
- [二、編寫Structured Streaming程式的基本步驟](#二編寫structured-streaming程式的基本步驟)
- [三、輸入源](#三輸入源)
  - [3.1 File源](#31-file源)
    - [（1）建立程式生成JSON格式的File源測試資料](#1建立程式生成json格式的file源測試資料)
    - [（2）建立程式對資料進行統計](#2建立程式對資料進行統計)
    - [（3）測試執行程式](#3測試執行程式)
    - [（4）處理警告](#4處理警告)
    - [（5）總結分析](#5總結分析)
  - [3.2 Kafka源](#32-kafka源)
    - [（1）啟動Kafka](#1啟動kafka)
    - [（2）編寫生產者（Producer）程式](#2編寫生產者producer程式)
    - [（3）安裝Python3的Kafka支援](#3安裝python3的kafka支援)
    - [（4）執行生產者程式](#4執行生產者程式)
    - [（5）編寫並執行消費者（Consumer）程式](#5編寫並執行消費者consumer程式)
      - [方式一](#方式一)
      - [方式二](#方式二)
    - [總結](#總結)
  - [3.3 Socket源](#33-socket源)
  - [3.4 Rate源](#34-rate源)



# 相關資料
相關資料內容

# 本文相關程式碼
本文相關程式碼內容

# 一、概述
概述內容

## 1.1 基本概念
基本概念內容

## 1.2 兩種處理模型
兩種處理模型內容

### （1）微批處理
微批處理內容

### （2）持續處理
持續處理內容

## 1.3 Structured Streaming和Spark SQL、Spark Streaming關係
Structured Streaming和Spark SQL、Spark Streaming關係內容

# 二、編寫Structured Streaming程式的基本步驟
編寫Structured Streaming程式的基本步驟內容

# 三、輸入源
輸入源內容

## 3.1 File源
File源內容

### （1）建立程式生成JSON格式的File源測試資料
建立程式生成JSON格式的File源測試資料內容

### （2）建立程式對資料進行統計
建立程式對資料進行統計內容

### （3）測試執行程式
測試執行程式內容

### （4）處理警告
處理警告內容

### （5）總結分析
總結分析內容

## 3.2 Kafka源
Kafka源內容

### （1）啟動Kafka
啟動Kafka內容

### （2）編寫生產者（Producer）程式
編寫生產者（Producer）程式內容

### （3）安裝Python3的Kafka支援
安裝Python3的Kafka支援內容

### （4）執行生產者程式
執行生產者程式內容

### （5）編寫並執行消費者（Consumer）程式
編寫並執行消費者（Consumer）程式內容

#### 方式一
方式一內容

#### 方式二
方式二內容

### 總結
總結內容

## 3.3 Socket源
Socket源內容

## 3.4 Rate源
Rate源內容

surprise

筆者在此將家底雙手奉上😎(❤️´艸｀❤️)，下列是一些有助於讀者瞭解並熟練掌握Markdown語法與結構的網站分享：
Markdown教程|菜鳥教程
Markdown 基本語法
Markdown 基本語法 | Markdown 官方教程
README檔案語法解讀，即Github Flavored Markdown語法介紹
Markdown Emoji表情
同時也分享一個RGB顏色程式碼表🎨

相關文章