8.5 KiB
코드·표·다이어그램·이미지
본문(bodyMarkdown)에만 해당한다. 본문이 있는 종류는 Case 와 Concept 이다.
코드블록
```java
@Query("select fi from FeedItem fi join fetch fi.user")
List<FeedItem> findFeed(Pageable pageable);
```
언어는 ^[A-Za-z0-9][A-Za-z0-9_.+-]*$만 쓴다 — java, kotlin, sql, yaml, bash,
text. 언어를 모르면 text.
설명을 붙이려면 label 하나만 쓴다. 다른 속성은 거절된다.
```sql label="N+1이 발생하는 조회"
SELECT * FROM highlights WHERE feed_item_id = ?;
```
코드에 자격증명·토큰·내부 호스트를 남기지 않는다. 지울 때는 지웠다는 사실이 보이게 한다 —
Authorization: Bearer <생략>처럼. 조용히 빼면 다음 사람이 그 헤더가 없었다고 읽는다.
붙여넣은 코드는 원문 그대로 둔다. 줄바꿈과 들여쓰기를 손보면 재현이 달라진다.
표
파이프로 그냥 쓴다. 감싸지 않는다.
| N | 초기화 컬렉션 | 총 쿼리 |
|---|---|---|
| 10 | 10 | 25 |
| 100 | 100 | 222 |
| 1,000 | 1,000 | 2,022 |
설명이나 행 머리글이 필요할 때만 :::table로 감싼다. 세 속성이 전부 있어야 한다.
:::table id="direct-measurement" caption="N별 직접 측정값" rowHeaderColumn="1"
| N | 초기화 컬렉션 | 총 쿼리 |
|---|---|---|
| 10 | 10 | 25 |
:::
id— 문서 안에서 유일해야 한다. 제목 id와도 겹치면 안 된다rowHeaderColumn—"1"이면 첫 열이 행 머리글, 아니면"none"- 정렬은 구분줄로 준다:
|---:|오른쪽,|:---:|가운데
측정값과 파생값을 한 표에 섞지 않는다. 섞어야 한다면 성격 열을 두어 어느 것이 잰 값이고 어느 것이 계산한 값인지 밝힌다.
머리글이 질문이면 행이 답이 된다
열 이름을 명사로 두면 독자가 표를 훑는다. 질문으로 두면 읽고 답을 얻는다.
| 쓰지 않는다 | 쓴다 |
|---|---|
memory-only가 줄이는가 |
memory-only가 위험을 막아주나..? |
남는 데이터 · reload 뒤 |
reload 전 · reload 후 |
확인함 · 확인 안 함 |
o · x |
비교 표의 축은 시점이나 상태로 못 박는다. 전·후, 켬·끔처럼 어느 때의 값인지 열
이름이 말해야 한다. 남는 데이터 같은 두루뭉술한 이름을 쓰면 그 열이 언제 얘긴지 본문을 다시
봐야 한다.
있음·없음을 가르는 열은 o·x로 채운다. 열이 좁아지고 값이 눈에 띄게 갈린다. 문장 안이 아니라
값 자리에서만 쓴다.
열을 줄인다. 감싸개가 --body-copy(672px)에 묶여 있고 표에는 min-width: 780px이 걸려
있어서, 열이 몇 개든 오른쪽 108px은 늘 잘린다. 3열을 2열로 줄일 수 있으면 줄이고, 첫 열
문구를 짧게 해서 값 열을 왼쪽으로 당긴다.
3열 2열로
| 방어선 | 무엇을 막나 | 뚫리면 | → | 위치 | 여기서 어떻게 막지? |
세 번째 열에 있던 내용은 표 다음 문단에서 이어 쓴다.
다이어그램·SVG
그림에 문장을 넣지 않는다
가장 흔한 실패다. 설명을 그림 안으로 밀어 넣으면 라벨이 길어지고, 글자는 작아지고, 검색도 복사도 화면 낭독도 안 되는 텍스트가 된다. 그림은 관계를 보이고 문장은 그 옆 문단에 쓴다.
지킬 선:
| 항목 | 기준 |
|---|---|
| 상자 | 7개 이하. 넘으면 그림을 나눈다 |
| 라벨 | 한 줄 40자 이하. 문장이 아니라 이름 |
| 글자 크기 | 2종 (제목·보조). 3종부터는 위계가 아니라 소음이다 |
| 색 | 의미를 색에만 싣지 않는다. 빗금·테두리·위치를 함께 쓴다 |
| 화살표 | 방향이 논지일 때만. 장식으로 긋지 않는다 |
| 숫자 | 넣지 않는다. 산문에 쓴다 |
빨강·초록 조합은 피한다. 색각 이상에서 구분되지 않는다.
자가 점검. 올리기 전에 <text>를 전부 뽑아 읽는다.
grep -o '<text[^>]*>[^<]*</text>' 그림.svg
하나라도 아래에 걸리면 문장이므로 뺀다. 길이가 아니라 서술하느냐가 기준이다 — 40자 이하여도 문장은 문장이다.
- 마침표나 물음표로 끝난다
- 서술어가 있다 —
~있다,~막는다,~바꿔도 - 조사로 두 대상을 잇는다 —
A를 B로,A에서 B까지
세 가지가 한 영역 안에 있다는 그림이 이미 보여 주는 것을 글로 다시 쓴 것이다. 상자를 한
영역 안에 그렸으면 그 문장은 필요 없다. 지우면 그림이 더 명확해진다.
<title>과 <desc>는 예외다. 화면을 못 보는 사람이 듣는 자리이므로 여기에는 문장을 쓴다.
그림 안에서 뺀 설명이 갈 곳이기도 하다.
무엇을 그릴지 정하는 법
그림 하나에 주장 하나다. "이 그림이 없으면 독자가 무엇을 못 보나"에 한 문장으로 답할 수 없으면 그리지 않는다. 표로 되는 것을 그림으로 그리지 않는다 — 표는 값을 비교하고, 그림은 포함·순서·경계처럼 자리로만 보이는 것을 맡는다.
Studio는 다이어그램을 그려 주지 않는다. 파일로 만들어 Asset으로 올린다.
본문에 Asset 삽입→업로드 종류를 다이어그램으로 →Asset 업로드- 목록에서 고르면 커서 자리에
:::evidence구문이 삽입된다
SVG는 image/svg+xml로 올라가고 다른 이미지와 같게 다뤄진다. 벡터라 확대해도 깨지지 않으니
구조도·흐름도에 맞다.
올리기 전에 SVG에서 지울 것:
<script>요소와on*속성- 외부 폰트·이미지 참조 — 열람자 환경에서 안 불러온다. 글자는 path로 변환하거나 일반 폰트만
- 절대 좌표에 의존하는 고정 크기 —
viewBox를 두어 늘어나게 한다
증거 이미지
:::evidence key="asset-key" alt="무엇을 보여 주는 그림인가" caption="설명" zoom="true"
:::
- 네 속성이 전부 있어야 한다. 본문은 비운다
key는^[a-z0-9]+(?:-[a-z0-9]+)*$zoom="true"면 눌러서 확대할 수 있다. 표·로그처럼 글자가 작으면 켠다alt는 화면을 못 보는 사람이 읽는 문장이다. "스크린샷"이 아니라 무엇이 보이는지 쓴다- 장식용 그림은 Asset의
decorative를 켜고alt를 비운다
READY가 아닌 Asset은 게시 시 거절된다.
저장소의 .md 에는 :::evidence 를 쓰지 않는다
:::evidence는 Studio 렌더러의 구문이다. 저장소의 .md를 그 형태로 쓰면 편집기에서 그림이
보이지 않고 구문이 글자로 남는다. 저장소는 읽는 형태로 쓴다.
alt는 그림의 alt를 그대로 쓰고, 경로는 frontmatter assets의 file과 같아야 한다.
Studio 로 보낼 때만 :::evidence 로 바꾼다. 손으로 고치지 않는다.
python3 scripts/studio-body.py <기록.md> -o /tmp/x.md # check_body 는 이 파일에 돌린다
python3 scripts/studio-body.py <기록.md> --body-only # Studio 에 붙여넣을 본문
python3 scripts/studio-body.py <기록.md> --key a=a-1a2b3c4d # 서버가 준 키로
Studio 파서는 상대 경로 이미지를 unsafe image URL로 거절하므로 check_body.mjs는 바꾼
파일에 돌린다. 저장소 파일에 그대로 돌리면 그림 자리에서 실패한다.
일반 이미지
Asset이 아닌 그림은 Markdown으로 쓴다.
문단 하나가 그림 하나로만 이루어져야 그림으로 인식된다. 글과 섞으면 인라인 이미지가 되어 거절된다.
설명이 필요하면 Markdown title을 쓰지 말고 — 거절된다 — :::evidence의 caption을 쓰거나
그림 다음 문단에 쓴다.
무엇을 어디에 쓰나
| 담을 것 | 쓸 것 |
|---|---|
| 명령어·설정·소스 | 코드블록 |
| 숫자 비교 | 표 |
| 구조·흐름 | SVG 다이어그램 Asset |
| 화면·로그 캡처 | 이미지 Asset + zoom="true" |
| 놓치면 안 되는 단서 | :::warning |
| 곁가지 설명 | :::note |
캡처로 표를 대신하지 않는다. 그림 속 숫자는 검색도 복사도 안 되고 화면 낭독기가 읽지 못한다.