실제 구현을 글에 넣고 싶다는 요청을 받으면서 설명과 실행을 함께 제공할 방법이 필요했다. 버튼을 누르고 값을 바꾸는 예제는 코드 사진보다 이해하기 쉽다. 나는 이번 편집실에서 글의 본문과 실행 예제를 서로 다른 문서로 다루는 구조를 만들고 그 조건을 다시 읽었다.
본문의 설명과 예제의 상태를 나눈다
글은 왜 이 기능을 만들었는지와 어떤 조건에서 쓸 수 있는지를 설명한다. 예제는 독자가 값을 바꾸고 결과를 확인하는 작은 작업 공간이다. 예제의 숫자가 바뀌어도 글의 제목과 문의 연결까지 함께 바뀔 필요는 없다. 그래서 HTML 구현은 본문 요소에 그대로 섞지 않고 별도 프레임의 문서로 전달했다.
현재 블록에는 제목과 설명, 높이와 실행 설정을 함께 남긴다. 예제 코드는 자기 문서의 요소를 찾아 변경한다. 공개 페이지에서 프레임과 코드를 전달했는지 확인할 수 있고 원고 버전에도 이 내용이 함께 들어간다. 설명과 예제가 따로 떠돌지 않도록 같은 원고에 보존하면서 실행 공간의 경계는 유지하는 선택이다.
스크립트 실행과 사이트 권한은 각각 정한다
현재 HTML 프레임은 scripts가 실제 참일 때 스크립트 실행 토큰을 붙인다. 같은 출처의 권한과 최상위 이동 권한은 이 프레임에 붙이지 않는다. 프레임의 sandbox와 콘텐츠 보안 정책을 함께 사용해 실행과 리소스 사용의 조건을 구체적으로 적었다. 이 설정을 읽는 것과 실제 브라우저에서 경계 동작을 시험하는 것은 다른 확인이다.
관리 API의 인증이나 원고 발행 권한을 예제에 넣지는 않는다. 공개 예제가 실제 고객 데이터를 바꾸는 도구라면 별도의 인증과 동작 범위가 필요하다. 지금 글의 계산과 상태 시뮬레이션은 예제 안에서 처리한다. 브라우저에서 보이는 버튼이 관리 API의 버튼처럼 보일 수 있으므로 제목과 설명에 그 실행 범위를 함께 남긴다.
필요한 기능만 블록의 선언에 남긴다
폼 제출과 다운로드, 새 창은 서로 다른 기능이다. 현재 구현에서는 이 기능들을 목록으로 선언하고 해당하는 토큰만 프레임에 붙인다. 계산 결과를 화면에 표시하는 예제라면 외부 제출 기능까지 열 이유가 없다. 다운로드 예제가 필요하면 파일 생성과 전달 방식도 설명하고 그 기능을 명시할 수 있다.
스크립트 실행도 기본 설정과 추가 실행 방식의 허용을 구별한다. 예제를 복사할 때 우연히 켜 둔 설정까지 다음 글로 전파되지 않게 원고의 블록 조건을 읽어야 한다. 내가 재사용하려는 것은 필요한 구현과 그 조건이다. 기능 이름이 늘어나는 것 자체를 홈페이지 품질로 삼지 않고 독자가 실제로 사용할 행동과 연결한다.
외부 자원과 내 미디어의 참조를 함께 읽는다
예제에 필요한 스크립트와 스타일, 연결과 프레임은 용도별 origin을 선언한다. 등록된 주소라도 모든 용도에 자동으로 넣지는 않는다. 사이트의 검토 목록과 개별 블록의 선언을 대조하는 구조다. 외부 서비스가 프레임 표시를 허용하는지와 네트워크 응답이 준비되어 있는지는 이후의 실제 연결에서 확인해야 한다.
내 미디어 서재의 파일은 현재 원고가 사용한다는 참조도 필요하다. HTML에 직접 적은 미디어 경로는 추출하고 동적으로 사용하는 파일은 media_ids에 명시할 수 있다. 코드가 파일 이름을 만들어 사용한다면 텍스트 검색만으로 그 관계를 전부 알 수 없다. 구현 코드와 공개할 자료의 목록을 함께 남기는 이유다.
문법과 전달, 브라우저 실행을 다른 검사로 남긴다
발행 전에는 인라인 코드의 문법을 검사하고 실패하면 API 저장 전에 멈춘다. 현재 공개 응답에서는 한영 예제의 프레임과 선언한 토큰, 콘텐츠 보안 정책이 전달되는지 확인했다. 새 로컬 검사에서는 실제 렌더러가 허용할 토큰을 만드는지도 확인했다. 이 근거들이 실제 클릭 결과를 대신하는 것은 아니다.
이번에는 기존 Studio Chrome 작업을 보존했고 새 PC·모바일 실행 화면과 경계 공격을 시험하지 않았다. 예제를 공개할 때 확인한 코드와 응답, 앞으로 확인할 브라우저 동작을 함께 적는다. 나는 설명을 읽은 독자가 직접 실행을 살펴볼 수 있게 하면서도 아직 보지 않은 결과를 확인된 경험으로 바꾸지 않으려 한다.