以下是 Exercism 中所有 Markdown 檔案應該遵循的結構方式。
這份文件中的部分規則尚未在整個 Exercism 全面實作。
我們歡迎大家送出 PR 來修正。
所有規則都會陸續加入我們的 CI 與 linting 工具，新的變更都應該遵守。
標題
- 所有檔案都必須以第 1 層標題（
# Some heading text）開頭。
- 第 1 層標題純粹是為了在 GitHub 或對等平台上使用。
- 如果檔案是由 Exercism 渲染（例如顯示在網站上、透過 CLI 渲染），這個標題會被移除，並插入一個符合情境的標題。
- 標題一次只能往下遞減一層，不能跳過層級（例如
##後面只能接###，不能接####）。
- 除了唯一的第 1 層（
#）標題之外，只能使用第 2 層（##）、第 3 層（###）和第 4 層（####）標題。
連結
請使用參考式連結，這種連結定義在 Markdown 檔案底部，對應到一個參考代稱，並在文中以該代稱引用。
這種做法讓維護更輕鬆，因為連結只需要在一個地方更新。
範例：
I have a paragraph of text that links to the same page twice.
The [first link][indirect-reference] in one sentence.
Then, another sentence with the [link repeated][indirect-reference].
[indirect-reference]: https://example.com/link-to-page
連結一定要有錨點文字，而不是直接把網址放進文字裡。例如下面這樣就沒有使用錨點文字，讀起來也比較吃力。
If you want some more information, please visit https://google.com.
使用錨點文字並加上連結，比較容易理解，也更容易看出上下文。
If you want some more information, [Google][google-link] is a useful resource.
[google-link]: https://google.com
渲染結果是：「如果你想要更多資訊，Google 是個很有用的資源。」
程式碼
只要提到程式碼元素（例如函式或關鍵字），就應該用反引號把程式碼包起來：
- The `printf()` function writes to the console.
渲染結果是：
- The
printf() function writes to the console.
比較複雜的程式碼（例如多行程式碼）應該用三個反引號包起來。開啟的三個反引號後面要指定語言識別碼，才能啟用語法突顯：
```python
# Define a variable
album = "Abbey Road"
```
情況允許的話，請依照程式碼實際呈現的環境來格式化。如果有的話，請參考你所使用語言的官方文件。
例如 Python 有 REPL（讀取、求值、輸出迴圈），讓程式設計師可以直接在終端機裡輸入程式碼。如果使用者正在除錯某段程式碼，或是在本機執行某個函式來測試、觀察它的運作方式，通常會偏好用 REPL，因為在那裡互動輸入比較方便。這種情況下，我們偏好把範例程式碼格式化成像是直接在 REPL 中輸入的樣子，並在前面加上>>>：
# This is the expected output a student would see while testing a function they wrote.
>>> print(extract_message("[INFO] Logline message"))
'Logline message'
其他情況下，把程式碼格式化成像是放在.py檔案裡會更合理。這麼做對學生有好處，因為呈現出來的樣子就跟他自己寫程式碼的方式很接近。
# presenting how functions are defined in Python:
def sample_func(argument1):
pass
當你分不清楚是哪一種情況時，有個快速的判斷方法：如果這是學生可以在終端機裡執行的程式碼，就那樣格式化。如果是 Exercism 可能會執行的程式碼（例如測試、學生會撰寫的函式庫程式碼等），就預設把它格式化成可直接執行的程式碼。
特殊區塊（有時稱為 admonition）
我們支援幾種特殊的區塊，可以加進文件裡，把不適合放在正文中的補充說明獨立出來。
我們支援三種區塊：
- **exercism/note:**用來特別帶出額外資訊的區塊
- **exercism/caution:**大家應該知道、或需要小心處理的事情
- **exercism/advanced:**只對想更深入鑽研某個主題、或被預期擁有更進階知識的人才有用的資訊。
所有區塊都使用 4 個波浪號撰寫，格式如下：
~~~~exercism/note
Content goes here
You can include code:
```ruby
str = "Hello, World"
```
A [reference link][forum-link] must have the link definition inside the block.
[forum-link]: https://forum.exercism.org/t/link-references-in-special-blocks-admonitions-are-not-rendered/3803
~~~~
（注意：在特殊情況下，你也可以使用反引號或其他層數的波浪號）
版面配置
一行一句
段落應該以一行一句的方式排版。Ascii Doctor 文件清楚說明了這麼做的道理。
例如，一個段落應該這樣排版：
Exercism has been designed, engineered and built by thousands of very talented individuals.
Nearly everything with Exercism has been debated, discussed and rewritten many times.
Exercism is a very intentional product - things are there because they've been designed to be there, and things are often left out because they've been designed to be left out.
清單
無序清單請使用連字號（-）作為項目符號。
註解
- 盡量使用 Markdown 註解，而不是 HTML 註解（例如使用
[comment]: # (Actual comment...) 而不是 <!-- Actual comment -->）
你可以在 babelmark3 用 commonmark 渲染看看你的註解，確認 Markdown 註解是否會被移除。
行內 HTML
- 允許行內 HTML，但應謹慎使用
- 如果有原生的 Markdown 寫法可用，就一律使用（例如使用
# ... 而不是 <h1>...</h1>）
圖片
由於網站支援淺色與深色主題，社群提交的圖片必須在兩種主題下都能清楚呈現。
解決方法是在圖片檔名加上後綴（放在副檔名之前）：
- 讓圖片檔名以
-invertible結尾（例如graph-invertible.svg）。在深色主題顯示時，圖片會自動反轉（透過filter: invert(100%)）。
- 讓圖片檔名以
-light結尾（例如graph-light.png），同時建立一個相容於深色主題、以-dark結尾的版本（也就是graph-dark.png）。我們會根據使用者的主題自動渲染正確的圖片。
兩種後綴都沒有的圖片，會在兩種主題下原樣使用。
這表示如果你想製作灰階圖片，通常可以讓它們在淺色主題下看起來不錯，再把它們設為可反轉。
但如果你用的圖片有很多顏色，不妨做兩個版本。
完整的圖片檔名（包含-invertible）應該寫進 Markdown 中圖片呈現的位置。
若是淺色／深色的圖片，請只放入-light版本。
這套邏輯在所有 Markdown 文件中都適用。
Linter
你可以用各種規則來設定 linter，以符合這份規格：
自動格式化
有些儲存庫使用 prettier 來確保所有 Markdown 的格式一致。這麼做有以下好處：
- 不需要討論格式。
- 與編輯器／IDE 整合良好，儲存檔案時就能自動格式化。
- 容易為格式加上 CI 檢查。
- 容易用指令碼自動格式化檔案。
以上這些都能大幅減少審查時的反覆更動，而反覆更動對審查者和被審查者來說都很惱人。
