텍스트·정규식
Markdown으로 읽기 쉬운 README 만들기
사용할 도구
사용법 질문이 반복되는 것은 정보 부족보다 찾기 어려움 때문일 수 있습니다. 긴 배경과 문장 속 명령은 언제 시작할지 모호하게 만듭니다. 원문과 미리보기를 비교하며 독자의 첫 작업 순서로 재배치하세요.
제목을 길잡이로 쓰기
# Example Tool
A small example for checking a local text file.
## Before you start
Use a fictional input file.
## Try one example
Follow the steps below.
## If the result differs
Check the input and selected options.붙여 넣고 문서 제목 아래 준비, 예제, 문제 해결 절이 있는지 확인하세요. 제목은 글자 크기보다 계층을 나타냅니다. 처음 실행하기, 결과가 다를 때처럼 작업 중심으로 이름을 붙이면 필요한 곳을 찾기 쉽습니다.
제목이 너무 많으면 흐름이 끊깁니다. 한 절에 질문 하나와 필요한 단계를 모으고 필수 전제는 짧게 쓴 뒤 예제 결과로 설명을 깊게 하세요. 미리보기는 글을 채점하지 않으므로 제목만 읽어 흐름을 이해할 수 있는지 직접 판단합니다.
입력과 예상 출력을 나누기
## Input
```json
{"name":"demo","enabled":true}
```
## Expected output
```text
Validation succeeded.
```펜스 코드 블록은 JSON과 줄바꿈 구조를 보여줍니다. 여기의 Validation succeeded.는 문서 예시이지 미리보기가 검증한 결과가 아닙니다. 결과 줄까지 명령이나 데이터로 복사하지 않도록 입력과 출력을 분리하세요.
코드 앞에 사용 위치와 바꿀 값을 적고 운영 인증 정보나 주소 대신 가상 값을 쓰세요. 코드가 표시된다고 명령이 동작하는 것은 아니며 프로젝트의 안전한 환경에서 별도로 확인해야 합니다.
비교는 표로, 순서는 번호로
| Option | Example | Meaning |
| --- | --- | --- |
| mode | preview | Inspect without applying |
| limit | 10 | Maximum displayed rows |같은 기준으로 여러 설정을 비교할 때는 표가 좋고 순서대로 할 작업은 번호 목록이 낫습니다. 긴 절차를 셀에 넣어 좁은 화면에서 반복해서 가로 스크롤하게 만들지 마세요.
mode와 limit은 문서 구성용 가상 예제이지 실제 도구 옵션이 아닙니다. 실제 지원 설정으로 바꾸고 예시값과 기본값을 구별하세요. 10이 예인지 미지정 시 적용값인지 독자가 알아야 합니다.
원문의 줄바꿈이 새 문단은 아닙니다
First line
Second line
Another paragraph처음 두 줄은 한 문단이고 빈 줄 뒤에 새 문단이 시작됩니다. 편집기의 줄바꿈과 의미상 문단 구분은 다릅니다. 문단마다 주제를 하나 두고 빈 줄로 나누며 미리보기로 구조를 확인하세요.
들여쓰기나 닫히지 않은 코드 펜스가 뒤 제목을 다른 요소 안으로 삼킬 수 있습니다. 뒤가 전부 코드로 보이면 시작 펜스까지 돌아가 보세요. 절 전체를 다시 쓰기 전에 경계, 들여쓰기, 빈 줄을 하나씩 바꿔 원인을 찾습니다.
미리보기 제한과 게시 환경은 다릅니다
미리보기는 외부 이미지를 가져오거나 원시 HTML을 실행하지 않고 링크도 이동용으로 활성화하지 않습니다. 이미지가 없다고 URL이 틀렸다고 단정할 수 없습니다. HTML 출력에 안전한 링크가 있어도 게시 사이트의 링크 검사는 별도입니다.
최종 사이트는 Markdown 확장, 앵커, 이미지 처리, CSS가 다를 수 있습니다. 여기서 구조를 보고 게시 위치에서도 확인하세요. 같은 모양이나 상대 링크 대상의 존재를 보장하지 않으므로 확인한 범위를 구분합니다.
처음 읽는 사람처럼 준비물, 입력, 성공 결과, 실패 시 다음 행동 네 가지를 찾아보세요. 흩어진 답을 작업 중심으로 모으고 헷갈리는 분기에 짧은 설명을 더하는 편이 일반 문장을 늘리는 것보다 유용할 수 있습니다.