누구를 위한 도구인가

문서를 정리 작업 없이 Markdown으로 옮기기

문서 이전은 보통 HTML을 변환한 뒤 변환기가 남긴 것을 지우는 데 더 오래 걸립니다. Clean Web Clipper는 바로 그 제거를 중심으로 만들어졌고, 측정한 것도 그 부분입니다. 페이지 512개에서 남은 HTML 태그 0개.

변환 뒤의 정리 작업

변환 자체는 1초면 됩니다. 일주일이 걸리는 것은 딸려 오는 모든 것입니다. 파일마다 맨 위에 반복되는 왼쪽 내비게이션, 버전 선택기, “이 페이지의 내용” 사이드바, 피드백 위젯, 이동 경로, 여덟 열짜리 푸터. 페이지 200개를 곱하면 이전은 원본 사이트마다 선택자가 다른 찾아 바꾸기 프로젝트가 됩니다.

그러고 나면 가장 필요했던 부분이 손상된 채 도착합니다. 코드 블록은 언어를 잃어 구문 강조가 사라지고, 독자는 셸 명령과 JSON 본문을 구별할 수 없습니다. 셀에 목록이 있는 표는 무너집니다. 경고 블록은 경고라는 표시가 없는 떠돌이 문단이 됩니다. 이것을 고치는 일은 찾아 바꾸기가 아니라 모든 페이지를 다시 읽는 일입니다.

아무도 계획하지 않는 것은 그 뒤의 감사입니다. 6주쯤 지나 누군가 새 사이트의 한 문단이 이전 사이트에 있던 것인지 이전 작업 중에 쓴 것인지 묻는데, 변환된 파일에 원래 주소가 없다면 원래 페이지를 찾는 것 말고는 답이 없습니다. 이미 내려간 문서 사이트라면 찾을 것도 없습니다. 가져온 파일마다 source 한 줄이면 이 질문이 정리되고, date 한 줄이면 어느 버전을 가져왔는지도 정리됩니다.

깔끔하게 대응되는 것

• 제목, 목록, 표, 코드 블록, 각주가 모두 표준 Markdown으로 대응됩니다.
• 코드 블록이 언어 태그를 유지합니다. 기술 코퍼스에서 156개 중 73개가 유지되었고, 비교한 엔진은 20개와 0개였습니다.
• 측정한 페이지 512개에서 남은 HTML 태그 0개.
• 내비게이션 사이드바, 버전 선택기, “이 페이지의 내용” 사이드바는 변환되지 않고 잘려 나갑니다.
• 경고와 강조 블록은 인용 블록이 됩니다. Markdown에는 이를 위한 표준 문법이 없기 때문입니다.
• 파일 이름 템플릿과 하위 폴더가 가져온 파일이 늘어나도 정리된 상태를 유지합니다.
• 모든 파일에 원래 주소가 담겨 있어서, 검토할 때 가져온 문단을 원래 페이지까지 추적할 수 있습니다.
• 각주는 새니타이저가 각주가 기대는 요소 id를 지우기 전에 모읍니다. 참조 링크가 살아남느냐를 가르는 순서의 문제입니다.

• 이 숫자의 출처: 엔진 버전과 날짜를 밝힌 벤치마크

## Workflow

Django can create migrations for you. Make changes to your models, then run:

```bash
python manage.py makemigrations
```

> **Note:** migrations are files on disk. Commit them with your code.

| Command         | What it does                              |
| --------------- | ----------------------------------------- |
| `makemigrations`| Writes new migrations from model changes  |
| `migrate`       | Applies migrations to the database        |

문서 이전용으로 설정하기

설정 두 가지, 폴더 하나, 커밋에 관한 작업 규칙 하나. 나중에 검토를 가능하게 하는 것은 커밋 규칙입니다.

1. 문서 저장소에 완성된 페이지가 들어갈 곳과 분리된 import/ 디렉터리를 만듭니다. 이전이 진행되는 동안 변환 원본과 편집한 페이지가 같은 폴더에 있으면 안 됩니다.
2. 확장 프로그램 아이콘에서 옵션을 열고, 저장 위치를 import/로 지정한 뒤 아이콘 클릭 동작을 “폴더에 저장”으로 설정합니다. 페이지 30개는 키 입력 30번이어야지 창 30개까지 되어서는 안 됩니다.
3. 이름 템플릿으로 {domain}-{title}을 고릅니다. 원본 사이트 두세 곳에서 가져오면 제목이 계속 겹치고, “Overview”가 overview-3이 되지 않게 막는 것이 도메인입니다.
4. frontmatter에서 title, source, extraction을 켭니다. source는 6주 뒤 감사 질문에 답하고, extraction은 어느 페이지가 렌더링된 내용이 아니라 구조화 데이터에서 왔는지 알려 줍니다.
5. 이미지는 제외하지 말고 링크로 둡니다. 그 URL을 계속 쓰지는 않겠지만 링크가 곧 목록입니다. 페이지에 도식이 있었다는 기록이고, 자산 작업을 계획할 때 필요한 것이 그것입니다.
6. 탭이나 아코디언이 있는 페이지는 클리핑하기 전에 엽니다. 확장 프로그램은 브라우저가 렌더링한 것을 변환하는데, 클릭해야 내용이 들어가는 탭은 클릭하기 전까지 DOM에 없습니다.
7. 가져온 원본을 커밋 하나로 먼저 커밋하고, 그 뒤 커밋에서 구조를 다듬습니다. 그래야 이후의 모든 diff가 변환 결과와 섞이지 않은 편집 변경만 보여 줍니다.

가져오기용 설정

한 번 읽고 잊는 폴더가 아니라, 사람이 한 페이지씩 검토한 뒤 편집할 파일 묶음에 맞춰 고른 값입니다.

## Installing

> **Warning:** upgrading across two major versions at once is not supported.

npm

```bash
npm install example-cli --save-dev
```

pnpm

```bash
pnpm add -D example-cli
```

두 탭 모두 DOM에 렌더링되어 있었으므로 둘 다 차례로 옮겨졌습니다.
클릭해야 렌더링되는 탭이었다면 옮겨지지 않았을 것입니다.

세 번의 이전

업체 문서 30페이지

파트너의 API 레퍼런스를 우리 문서에 넣어야 합니다. 페이지 30개를 키 한 번씩 눌러 import/에 클리핑합니다. 코드 블록은 태그가 붙어 도착합니다. 기술 코퍼스에서 언어 태그는 156개 중 73개에 남았고 비교한 엔진은 20개와 0개였으며, 왼쪽 내비게이션, 버전 선택기, 피드백 위젯은 아무 데도 도착하지 않습니다.

그다음 편집하는 것은 산문과 구조입니다. 편집하지 않아도 되는 것은 HTML을 그대로 변환했다면 파일마다 맨 위에 쌓였을 페이지당 사이드바 200줄이고, 이전이 몇 주씩 걸리는 진짜 이유가 그것입니다.

경고 블록으로 가득한 가이드

원본 가이드가 경고, 참고, 팁 블록에 크게 기대고 있습니다. Markdown에는 그중 어느 것에도 표준 문법이 없으므로 셋 다 인용 블록이 됩니다. 내용은 살아남고 세 종류의 구분은 살아남지 않습니다.

이 점은 시작한 뒤가 아니라 시작하기 전에 알아 둘 가치가 있습니다. 종류별로 다시 표시하는 것은 수작업이고 그 규모는 원본에 달려 있기 때문입니다. 가져온 원본에서 인용 블록을 찾아보면 그 작업 범위가 잡히고, 그것은 페이지별 읽기가 아니라 grep 한 번입니다.

사이트가 꺼지기 전의 구조 작업

제품이 단종되고 문서가 월말에 내려갑니다. 여기에는 크롤러가 없으므로 한 페이지씩 해야 하지만, 각 페이지는 머리글에 원래 주소가 담긴 파일로 도착하고, 그것이 구조한 자료를 나중에도 쓸모 있게 만듭니다.

따로 계획할 것은 이미지입니다. 곧 사라질 사이트로 가는 링크로 남으므로, 중요한 페이지는 기한 전에 도식을 손으로 저장해야 합니다. 가져온 파일 속 링크 목록이 그 작업의 체크리스트입니다.

다른 변환 방법과 비교

이전 작업은 대개 이 중 두 가지를 함께 쓰게 됩니다. 솔직한 비교는 수작업이 있느냐가 아니라 어디에 떨어지느냐입니다.

가져온 뒤 손봐야 할 것

경고 블록이 모두 똑같아 보입니다

경고, 참고, 팁이 모두 인용 블록이 됩니다. Markdown에는 대응시킬 표준 경고 블록 문법이 없기 때문입니다. 텍스트는 온전하고 줄 앞의 강조 표시도 대개 남으므로, 굵은 “Warning:”으로 시작한 경고는 여전히 그렇게 적혀 있습니다. 종류별 재표시는 계획해 둘 작업이고, 그 규모는 인용 블록을 찾는 grep 한 번이면 알 수 있습니다.

맨 위에 제목이 없는 페이지가 들어왔습니다

빈 제목은 버려지는데, 많은 문서 사이트에서 눈에 보이는 페이지 제목은 제목 요소가 아니라 기사 본문 밖의 내비게이션 요소입니다. 제목은 페이지 자체의 메타데이터에서 가져온 title frontmatter 필드로 여전히 파일에 들어갑니다. 그것을 H1으로 올리는 것은 가져온 파일 전체에 스크립트로 적용할 수 있는 기계적인 단계입니다.

이미지 링크가 여전히 이전 사이트를 가리킵니다

그렇습니다. 확장 프로그램은 바이너리 자산을 내려받지 않으므로 모든 이미지는 원래 있던 곳으로 가는 링크이고, 가져온 파일 묶음은 자체 완결되지 않습니다. 링크를 결과가 아니라 목록으로 다루세요. 어느 페이지에 자산이 몇 개 있는지 알려 주며, 자산 이전에 필요한 목록이 정확히 그것입니다.

jsonld-articlebody가 기록된 페이지가 사이트와 다르게 읽힙니다

그 페이지는 기사 텍스트를 구조화 데이터로 보냈지만 렌더링을 끝내지 않았으므로, 본문을 구조화 데이터에서 가져왔습니다. 둘이 항상 같지는 않습니다. 렌더링된 페이지를 구조화 데이터보다 자주 고치는 사이트는 그 블록에 이전 버전을 남깁니다. 커밋하기 전에 원본과 대조해 읽어야 할 페이지가 바로 그것들입니다.

이것이 아닌 것

이전 도구가 아닙니다. 크롤러도, 링크 재작성도, 리디렉션 맵도, 자산 다운로드도 없습니다. 이미지는 원래 사이트로 가는 링크로 남으므로 가져온 파일 묶음은 자체 완결되지 않습니다. Markdown이 표현할 수 없는 것(탭으로 나뉜 코드 블록, include, 경고 블록 종류, 사용자 정의 컴포넌트)은 가장 가까운 일반 표기로 펼쳐지므로, 내용은 살아남고 스타일은 살아남지 않습니다. 그리고 페이지가 렌더링한 것을 변환하므로, 열지 않은 아코디언 속 텍스트는 DOM에 없어 클리핑되지 않습니다.

자주 묻는 질문