Markdown은 허용됩니다.구조적 실수가 있는 문서는 여전히 렌더링될 수 있으므로 표가 깨지거나 탐색에서 제목이 사라지거나 화면 판독기 사용자에게 이미지가 의미가 없게 될 때까지 이러한 실수를 놓치기 쉽습니다.
Markdown 린팅은 출판 전에 소스 텍스트의 구조적, 접근성 및 일관성 문제를 확인하는 프로세스입니다.다음으로 시작하세요. Markdown 린터 건너뛴 제목 수준, 누락된 이미지 대체 텍스트, 베어 URL, 레이블이 없거나 닫히지 않은 코드 펜스 및 후행 공백을 포착합니다.그런 다음 광범위한 편집 검토를 위해 이 가이드의 수동 체크리스트를 사용하세요.
Linting은 임의의 기본 설정을 적용하는 것이 아닙니다.유용한 규칙은 실제 읽기, 렌더링, 유지 관리 또는 접근성 문제를 방지해야 합니다.
빠른 사전 게시 체크리스트
| 확인 | 이것이 중요한 이유 | 자동 또는 수동? |
|---|---|---|
| 제목 계층 구조 | 문서 구조를 보존합니다. | 린터 |
| 이미지 대체 텍스트 | 시각 없이도 이미지를 이해할 수 있게 만듭니다. | 린터 |
| 설명 링크 | 접근성 및 검색을 개선합니다. | Linter + 수동 검토 |
| 폐쇄형 코드 펜스 | 페이지의 나머지 부분이 코드가 되는 것을 방지합니다. | 린터 |
| 코드 언어 라벨 | 유용한 구문 강조를 활성화합니다. | 린터 |
| 후행 공백 | 보이지 않는 방언 관련 동작을 방지합니다. | 린터 |
| 명확한 페이지 제목 1개 | 페이지 목적을 명확하게 유지합니다. | 수동 검토 |
| 일관성 목록 | 중첩이 깨지는 것을 방지합니다. | 수동 검토 |
| 유효한 테이블 | 열 구조를 그대로 유지합니다. | 수동 검토 |
| 고유 제목 | 중복 앵커 혼동 방지 | 수동 검토 |
| 휴대용 HTML 사용법 | 렌더러 관련 오류를 방지합니다. | 수동 검토 |
| 읽을 수 있는 단락 | 이해력 향상 | 수동 검토 |
대표 문서를 린터에 붙여넣고 검사를 실행하고 보고된 줄을 수정한 다음 실제 게시 시스템에서 전체 페이지를 미리 봅니다.
1. 건너뛴 제목 수준
문제
# Deployment Guide
### Configure credentials
문서가 H1에서 H3으로 이동합니다.글꼴 크기가 눈에 보이는 유일한 신호이지만 구조적 윤곽선에 수준이 누락된 경우에는 허용 가능한 것처럼 보일 수 있습니다.
수정
# Deployment Guide
## Configure credentials
시각적 크기를 선택하는 것이 아니라 계층 구조를 설명하려면 제목을 사용하십시오."인증 정보 구성"이 실제로 누락된 섹션에 속하는 경우 해당 섹션을 추가하세요.
# Deployment Guide
## Preparation
### Configure credentials
해당 Markdown 린터 에서는 두 수준 이상으로 이동하는 제목을 보고합니다.
2. H1 제목이 여러 개이거나 누락됨
페이지에는 일반적으로 하나의 명확한 제목이 있어야 합니다.일부 문서 시스템은 머리말에서 H1을 생성하는 반면 다른 문서 시스템에서는 Markdown 본문에서 H1을 생성합니다.귀하의 사이트에서 어떤 규칙을 사용하는지 알아보세요.
모호한 소스
# Installation
# Configuration
소스 지우기
# Product setup
## Installation
## Configuration
사이트 템플릿이 렌더링되는 경우 title: Product setup 페이지 H1과 같이 본문은 대신 H2로 시작할 수 있습니다.규칙은 "모든 Markdown 파일이 정확히 하나의 파일을 포함해야 한다는 것이 아닙니다. #.” The rule is “the rendered page needs one unambiguous primary heading.”
3. 강조 목적으로만 사용되는 제목
이 소스는 불필요한 개요 항목을 생성합니다.
#### Important!
텍스트에 섹션이 소개되지 않으면 산문이나 적절한 콜아웃을 사용하세요.
**Important:** Back up the database before continuing.
제목은 독자가 탐색하는 데 도움이 되어야 합니다.장식적인 제목은 목차를 복잡하게 만들고 보조 탐색의 유용성을 감소시킵니다.
4. 대체 텍스트가 없는 이미지
문제

이미지에 대체 텍스트가 없습니다.그것을 볼 수 없는 독자는 어떤 설명도 듣지 못하고, 깨졌거나 비활성화된 이미지를 보는 사람은 그 목적을 알 수 없습니다.
수정

이미지의 외양만이 아니라 이미지가 제공하는 정보를 설명하세요.매체가 중요하지 않다면 '이미지'와 같은 문구는 사용하지 마세요.
장식 이미지는 특별한 경우입니다.이미지에 정보가 전달되지 않는 경우 HTML에서는 빈 대체 텍스트가 정확할 수 있지만 Markdown 렌더러와 콘텐츠 워크플로는 다릅니다.이미지가 순전히 장식용인 경우 먼저 해당 이미지가 기술 문서에 속하는지 물어보십시오.
linter는 빈 대체 텍스트가 있는 Markdown 이미지에 플래그를 지정합니다.는 이미지 포맷터 는 명시적인 대체 및 선택적 캡션이 포함된 이미지 마크업을 생성할 수 있습니다.
5. 약하거나 노출되지 않은 링크
문제
Visit https://example.com/docs/setup for more information.
베어 URL은 검사하기 어렵고 소리내어 읽을 때 불쾌할 수 있습니다.일반 링크 텍스트는 그다지 좋지 않습니다.
[Click here](https://example.com/docs/setup).
수정
Read the [service setup guide](https://example.com/docs/setup).
설명 링크는 독자에게 무엇을 열 것인지 알려줍니다.또한 링크 목록으로 추출해도 의미가 유지됩니다.
린터는 많은 베어 http:// and https:// URL이지만 링크 텍스트가 유용한지 판단하려면 여전히 편집 검토가 필요합니다.
6. 닫히지 않은 코드 펜스
문제
```javascript
const status = 'ready';
## Next section
닫는 울타리가 없으면 렌더러가 페이지의 나머지 부분을 코드로 처리할 수 있습니다.
수정
```javascript
const status = 'ready';
```
## Next section
닫히지 않은 울타리로 인해 유효한 문서의 큰 부분이 깨질 수 있습니다.린터는 일치하지 않는 펜스가 시작되는 라인을 보고합니다.
7. 언어 식별자가 없는 코드 펜스
덜 유용함
```
npm run build
```
더 좋음
```bash
npm run build
```
언어 식별자는 구문 강조를 활성화하고 독자가 보고 있는 콘텐츠의 종류를 전달합니다.다음과 같은 공통 식별자를 사용하십시오. javascript, typescript, json, html, css, bash, powershell, yaml또는 markdown.
단지 색상을 얻기 위해 부정확한 언어를 추가하지 마십시오.구조화되지 않은 출력의 경우 다음을 사용하십시오. text 대상이 이를 인식하는 경우.
8. 일관성 없는 목록 들여쓰기
문제
- Install dependencies
- Production packages
* Development packages
- Optional tools
혼합된 탭, 공백 및 마커는 검토하기 어렵고 다양한 수준에서 렌더링될 수 있습니다.
수정
- Install dependencies
- Production packages
- Development packages
- Optional tools
프로젝트에 대해 일관된 들여쓰기 너비를 선택하십시오.정확한 공백 수는 Markdown 방언 및 목록 내용에 따라 달라질 수 있지만 일관성이 필수적입니다.
사용 중첩 목록 포맷터 최종 검토 전에 혼합된 글머리 기호, 번호 매기기, 탭 및 들여쓰기를 정규화합니다.
9. 수동으로 입력된 숫자 시퀀스
번호가 긴 목록은 유지 관리 비용이 많이 듭니다.
1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.
많은 Markdown 렌더러에서는 모든 항목을 사용할 수 있습니다. 1. 여전히 순서가 지정된 시퀀스를 표시하는 동안:
1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.
이렇게 하면 소스 차이의 번호 다시 매기기 노이즈가 줄어듭니다.그러나 명시적으로 번호가 매겨진 소스는 지침이 "3단계"를 참조할 때 논의하기가 더 쉽습니다.하나의 프로젝트 규칙을 선택하고 일관되게 적용하십시오.
입력된 숫자, 순서 목록 표시자 및 단락 텍스트를 결합하지 마십시오.중첩된 단계를 편집한 후 렌더링된 결과를 확인합니다.
10. 잘못된 테이블
문제
| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |
구분 기호와 데이터 행에 동일한 논리적 개수의 열이 포함되어 있지 않습니다.
수정
| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |
또한 셀 내부에 이스케이프 처리되지 않은 파이프 문자가 있는지 확인하세요.
| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |
해당 Markdown 표 포맷터 은 고르지 않은 행을 노출하고 정렬된 소스를 생성하는 데 도움이 됩니다.시각적으로 새 테이블을 생성하려면 Markdown 테이블 생성기.
11. 중복된 제목 및 앵커 충돌
문서는 "예"와 같은 눈에 보이는 제목을 합법적으로 반복할 수 있지만 자동으로 생성된 앵커 ID는 #examples, #examples-1및 #examples-2.정확한 규칙은 렌더러에 따라 다릅니다.
제목이 반복되면 수동 링크가 취약해집니다.
- [API examples](#examples)
- [CLI examples](#examples)
설명이 포함된 제목을 선호하세요:
## API examples
## CLI examples
그런 다음 다음을 사용하여 목차를 생성합니다. Markdown TOC 생성기 및 대상 플랫폼의 앵커를 확인합니다.
12. 후행 공백
줄 끝의 공백이 표시되지 않습니다.일부 Markdown 방언에서는 두 개의 후행 공백이 하드 줄 바꿈을 생성합니다. 이는 실수로 인한 편집기 작업으로 인해 렌더링이 변경될 수 있음을 의미합니다.
linter는 후행 공백을 보고하므로 의도적인 것인지 여부를 결정할 수 있습니다.단락 구분을 위해 빈 줄을 선호합니다.엄격한 줄 바꿈이 정말로 필요한 경우 프로젝트에서 선택한 규칙을 일관되게 문서화하고 적용하십시오.
편집자는 일반적으로 저장 시 자동으로 후행 공백을 제거할 수 있지만 이로 인해 레거시 콘텐츠에서 의도적인 줄 바꿈이 변경되지 않는지 확인하십시오.
13. 이식성을 감소시키는 원시 HTML
Markdown에서는 종종 HTML 임베디드를 허용합니다.
<div class="warning-panel">
Restarting the service ends active sessions.
</div>
해당 블록은 한 웹 사이트에서 작동하지만 다른 곳에서는 이스케이프되거나 삭제되거나 스타일이 잘못 지정될 수 있습니다.동일한 의미를 표현할 수 있는 휴대용 Markdown을 선호합니다.
> **Warning:** Restarting the service ends active sessions.
Markdown이 표현할 수 없는 기능(예: 제어된 이미지 크기 또는 지원되는 기능)에 대해 의도적으로 HTML을 사용하십시오. <details> 블록.콘텐츠가 렌더링되어야 하는 대상 목록을 유지하고 각 대상을 테스트하세요.
해당 콜아웃 생성기 는 이식성이 기본 프레젠테이션보다 덜 중요한 경우 GitHub, Obsidian 및 MkDocs에 대한 플랫폼별 구문을 생성할 수 있습니다.
14. 단락이 너무 길고 스캔 가능성이 낮음
Markdown은 구조적으로 유효하지만 여전히 읽기 어려울 수 있습니다.여러 결정, 경고, 절차를 포함하는 텍스트 벽을 재구성해야 합니다.
사용:
- 하나의 주요 아이디어에 대한 짧은 단락;
- 탐색에 대한 설명 제목;
- 병행 항목 목록;
- 테이블;
- 코드 블록;
- 소수의 중요한 예외에 대한 설명입니다.
모든 문장을 글머리 기호로 바꾸지 마십시오.목록은 항목이 동일한 문법적, 개념적 역할을 가질 때 가장 잘 작동합니다.
사용 단어 수 및 읽기 시간 은 단락 수, 제목 수 및 읽기 길이를 검사하지만 통계를 대상이 아닌 신호로 처리합니다.
15. 호환성 계획이 없는 렌더러 관련 구문
GitHub 작업 목록, Obsidian 위키 링크, MkDocs 경고, 각주, 정의 목록 및 머리말은 모두 유용하지만 모든 곳에서 동일하게 지원되지는 않습니다.
예를 들어:
> [!NOTE]
> This callout is useful in destinations that recognize the syntax.
확장을 채택하기 전에 다음 세 가지 질문에 답하십시오.
- 어떤 렌더러가 최종 출력을 소유합니까?
- 콘텐츠를 나중에 다른 곳으로 옮겨야 합니까?
- 확장이 지원되지 않으면 독자는 무엇을 보게 됩니까?
이식 가능한 Markdown 기반을 유지하고 가능하면 게시 에지에 플랫폼 구문을 추가하십시오.
실용적인 Linting 작업 흐름
1단계: 구조 확인
소스를 Markdown 린터.오류를 먼저 수정한 다음 경고를 수정하고 정보 일관성 항목을 수정합니다.자동 검사를 통해 위치를 식별해야 합니다.의미를 조용히 다시 써서는 안 됩니다.
2단계: 어려운 요소 정규화
기계적 정리를 위해 집중 도구를 사용하십시오.
- 중첩 목록 포맷터 ;
- Markdown 표 포맷터 ;
- 이미지 포맷터 ;
- 목차 생성기 입니다.
집중된 변경은 전체 파일을 다시 작성하는 광범위한 포맷터보다 더 작고 검토하기 쉬운 diff를 생성합니다.
3단계: 문서 미리보기
다음에서 소스를 엽니다. Markdown 편집자 및 Markdown를 렌더링된 출력과 비교합니다.확인:
- 제목 및 목차;
- 목록 및 작업 목록;
- 테이블;
- 이미지 및 링크;
- 코드 블록 및 인라인 코드;
- 콜아웃 또는 원시 HTML.
4단계: 실제 대상 테스트
일반 미리 보기에서는 모든 렌더러를 재현할 수 없습니다.게시하기 전에 GitHub, Obsidian, GitLab, MkDocs 또는 실제 문서 사이트에서 파일을 엽니다.
5단계: 구문뿐 아니라 의미 검토
어떤 린터도 절차가 안전한지, 링크가 의도한 정책을 가리키는지, 이미지 설명이 중요한 결론을 전달하는지 확인할 수 없습니다.검토자는 정확성, 완전성, 어조, 청중 적합성을 확인해야 합니다.
팀 스타일 가이드 권장 사항
수십 가지의 무언의 선호보다 간단하게 문서화된 규칙이 더 효과적입니다.정의:
- 페이지 제목이 머리말 또는 Markdown 본문에 있는지 여부;
- 허용된 제목 진행;
- 목록 들여쓰기 및 순서 목록 스타일;
- 코드 펜스 언어 요구 사항;
- 이미지와 대체 텍스트를 검토하는 방법
- 테이블 복잡성 제한;
- 에서는 HTML 및 플랫폼 확장을 허용했습니다.
- 최대 라인 길이(팀이 사용하는 경우)
- 링크 확인 방법;
- 은 Linter 규칙으로 인해 게시가 차단됩니다.
실제 결함을 방지하는 규칙부터 시작하세요.팀이 해결하는 문제를 이해하는 경우에만 규칙을 추가하세요.
FAQ
유효한 Markdown에 자동으로 액세스할 수 있습니까?
아니요. 유효한 구문에는 여전히 빈 대체 텍스트, 모호한 링크, 혼란스러운 제목, 액세스할 수 없는 다이어그램, 잘못된 읽기 순서가 포함될 수 있습니다.접근성에는 구조적 및 편집적 검토가 필요합니다.
Markdown Linter가 내 문서를 다시 작성합니까?
WordToMD Linter는 줄 번호 문제를 보고합니다.소스를 자동으로 다시 작성하지 않으므로 각 수정 사항을 계속 제어할 수 있습니다.
Linter가 기본 URL을 보고하는 이유는 무엇입니까?
설명 링크 텍스트는 스캔하기 쉽고 보조 기술에 더 유용합니다.리터럴 주소가 독자에게 필요한 정보가 아닌 한 URL을 의미 있는 레이블로 바꾸십시오.
레이블이 없는 코드 펜스는 항상 잘못된 것입니까?
항상 그런 것은 아니지만 올바른 언어 식별자를 사용하면 일반적으로 명확성과 구문 강조가 향상됩니다.사용 text 입니다.
모든 프로젝트가 동일한 린팅 규칙을 사용해야 합니까?
아니요. GitHub README, Obsidian 저장소, API 참조 및 게시 사이트에는 서로 다른 규칙이 있습니다.구조적 및 접근성 규칙의 핵심 세트를 공유한 다음 목적지별 검사를 추가하세요.
린팅이 교정을 대체할 수 있습니까?
아니요. 린터는 패턴을 감지합니다.기술적 진실, 주장의 질, 사용자 의도 또는 문장이 문맥상 이해 가능한지 여부를 안정적으로 확인할 수 없습니다.
결론
좋음 Markdown은 렌더링되는 소스 그 이상입니다.명확한 개요, 의미 있는 링크, 접근 가능한 이미지, 완전한 코드 펜스, 일관된 목록, 유효한 테이블 및 출판 플랫폼과의 정의된 관계가 있습니다.
다음을 실행하세요. Markdown 린터 빠른 구조 검사를 위해 Markdown 편집자 은 시각적 검토를 위한 것이며 소스를 더 쉽게 유지 관리할 수 있는 경우에만 집중 포맷터를 적용하십시오.그 결과, 향후 편집 시 더 이식성이 있고, 접근 가능하며, 신뢰할 수 있는 Markdown가 탄생했습니다.