呈現方式

本文件說明各種練習與軌道檔案會如何呈現給學生，並考量學生使用的是 CLI 還是編輯器。

說明文件

有三種類型的說明文件，決定了某道練習會呈現哪些說明文件。

練習專屬檔案

這些檔案是每道練習專屬的：

  • .docs/introduction.md：向學生介紹這道練習所教的概念（必填）
  • .docs/introduction.append.md：接在現有簡介之後的額外簡介文字（概念練習不使用，實作練習為選填）
  • .docs/instructions.md：提供這道練習的指示（必填）
  • .docs/instructions.append.md：接在現有指示之後的額外指示文字（概念練習不使用，實作練習為選填）
  • .docs/hints.md：提供提示，幫助學生自己突破卡關（概念練習必填，實作練習選填）
  • .meta/config.json：包含這道練習的來源資訊（選填）

詳見概念練習說明文件與實作練習說明文件。

軌道專屬檔案

這些檔案由所有練習共用：

  • debug.md：說明在瀏覽器中寫程式的學生要如何進行「除錯」（選填）
  • help.md：包含該軌道專屬的求助說明（必填）
  • representations.md：說明會對解答套用哪些正規化，以產生它的表示（選填）
  • tests.md：包含該軌道專屬的執行測試說明（必填）

詳見共用檔案說明文件。

Exercism 全站說明文件

除了上述的軌道／練習專屬說明文件之外，還有兩部分是 Exercism 全站通用的（因此所有軌道共用）：

  • 如何使用 CLI 提交練習的指示
  • 如何尋求協助的指示

編輯器

在瀏覽器中進行練習時，說明文件會在適當的時機顯示。舉例來說，除非學生主動要求，否則不會顯示提示。編輯器也不需要顯示 CLI 的指示。

CLI

當透過 CLI 在本機端工作時，我們無法選擇性地顯示說明文件。因此，CLI 一律必須下載所有相關的說明文件。為了不讓學生需要開啟多個檔案，CLI 會將所有相關說明文件串接成三份文件：

README.md

這個檔案包含這道練習的指示、簡介（選填）與來源資訊（選填）。

# [exercise name]

Welcome to [exercise name] on Exercism's [track name] Track.
If you need help running the tests or submitting your code, check out `HELP.md`.
If you get stuck on the exercise, check out `HINTS.md`, but try and solve it without using those first :)

## Introduction (optional)

[Exercise-specific file: .docs/introduction.md] (optional)

[Exercise-specific file: .docs/introduction.append.md] (optional)

## Instructions

[Exercise-specific file: .docs/instructions.md]

[Exercise-specific file: .docs/instructions.append.md] (optional)

## Source

### Created by

- @[author-1 handle]
- @[author-2 handle]
  ...

### Contributed to by (optional)

- @[contributor-1 handle]
- @[contributor-2 handle]
  ...

### Based on

[source] - [source url]

HELP.md

這個檔案說明如何執行測試，以及軌道專屬與 Exercism 全站通用的求助說明。

# Help

## Running the tests

[Track-specific file: exercises/shared/.docs/tests.md]

## Submitting your solution

[Exercism-wide documentation: instructions on how to submit a solution]

## Need to get help?

[Exercism-wide documentation: instructions on how to get help]

[Track-specific file: exercises/shared/.docs/help.md]

HINTS.md

這個檔案包含這道練習專屬的提示（選填）

# Hints

## General

- Consider extracting the logic to a helper function.