설정 사전: GA4 방문 통계와 AI 읽기 보충 설명
통계 ID와 운영 로드 조건, 공개 기계 읽기 텍스트의 사이트 보충 설명입니다.
목차
첫 배포는 배포 가이드를 읽으세요. 통계 ID 취득과 공개 텍스트 용도를 안내합니다. 설정 위치는 설치와 사이트 정보, 다른 모듈은 설정 사전 시작 페이지에 있습니다.
두 설정은 src/site.config.ts 최상위에서 site, theme와 같은 수준에 있습니다. analytics는 방문 통계, aiReadableContent는 공개 사이트 보충 문구입니다. 서로 독립적이므로 통계에 AI 보충을 넣거나 공개 텍스트에 통계 ID를 넣을 필요는 없습니다.
analytics.googleAnalyticsId: GA4 식별자
| 경로 | 타입 / 기본값 | 상태·역할·제한 | 예시 값 |
|---|---|---|---|
| analytics | { googleAnalyticsId: string } / { googleAnalyticsId: ‘’ } | 설정 컨테이너이며 일부만 덮어쓸 수 있습니다. 추가 enabled 필드는 없습니다. | { googleAnalyticsId: ‘G-XXXXXXXXXX’ } |
| analytics.googleAnalyticsId | string / ‘’ | 조건부 적용: 유효 ID, 운영 빌드, 로컬 주소 제외 규칙에 해당하지 않을 때 GA4를 로드합니다. 빈 문자열·공백은 끄고 앞뒤 공백을 제거합니다. 정규식은 ^G-[A-Z0-9]+$이며 접두사·후속 문자는 대문자여야 합니다. 형식 오류는 컴포넌트 해석 시 예외입니다. | ‘G-XXXXXXXXXX’ |
GA4 웹 데이터 스트림의 Measurement ID입니다. 숫자 속성 ID, GTM 컨테이너 ID, 옛 UA ID, API 키가 아닙니다. 예시는 형식만 보여 주므로 실제 값을 넣으세요. 고정 길이를 요구하지 않으며 온라인으로 스트림의 유효성을 확인하지 않습니다. “정규식 통과”는 “통계 수신”이 아닙니다.
analytics: {
googleAnalyticsId: 'G-XXXXXXXXXX',
},
끄려면 합치세요.
analytics: { googleAnalyticsId: '' },
기존 defineThemeConfig({...})에 합치고 analytics를 중복 생성하지 마세요. 하나의 ID를 공용 프레임워크의 모든 언어 페이지에 사용하며 언어·페이지별 ID 필드는 없습니다.
언제 로드하나요?
| 환경·주소 | 현재 동작 |
|---|---|
| npm run dev | 로더를 출력하지 않습니다. 필드는 먼저 해석하므로 잘못된 형식을 무시한다고 보장하지 않습니다. |
| 운영 빌드, 빈 ID | 통계 로더를 출력하지 않습니다. |
| 운영 빌드, localhost 또는 .localhost 하위 도메인 | 로더가 미리 반환하며 테마 통계 큐를 초기화하거나 Google을 요청하지 않습니다. |
| 운영 빌드, 127. 시작 주소·0.0.0.0·::1·[::1] | 마찬가지로 건너뜁니다. 비교 전에 소문자로 바꿉니다. |
| 운영 빌드, LAN IP·원격 미리보기 도메인 | “미리보기”라는 이유로 제외하지 않습니다. ID가 있으면 로드를 시도합니다. |
| 운영 빌드, 정식 도메인·유효 형식 ID | gtag 큐를 한 번 초기화하고 Google 클라이언트를 비동기 삽입합니다. |
js 초기화와 config 명령을 실행하며 별도 page_view를 수동 추가하거나 검색어·플레이어 같은 사용자 이벤트를 넣지 않습니다. 같은 로더에는 한 번 실행 표식이 있지만 다른 도구로 설치한 통계는 식별하지 않습니다. 수동 스크립트·GTM이 있다면 중복 설치를 확인하세요.
기존 window.dataLayer, window.gtag는 유지합니다. 동의 관리 패널, 자동 동의 설정, 프록시 전송, 제외 도메인 목록, 사용자 이벤트 설정은 없습니다. 전용 PUBLIC_GA_* 변수로 ID를 자동 덮어쓰지 않습니다. 환경 제어는 site.config에서 명시적으로 처리해야 하며 임의 변수 이름을 넣어도 테마가 읽지 않습니다.
구형 사용자 adapter에 ANALYTICS 분기가 없으면 미설정으로 처리하는 내부 호환 대체가 있습니다. 권장 입력 경로가 추가되는 것은 아니며 analytics.googleAnalyticsId만 씁니다.
aiReadableContent: 전역 공개 보충
생략 가능한 MachineReadableSupplement 객체이며 테마 기본은 미설정입니다. 생략해도 기계 읽기 파일은 생성하며 추가 설명만 붙이지 않습니다. {}도 내보내기 끄기 스위치가 아닙니다.
| 전체 경로 | 타입 / 기본값 | 상태·역할·제한 | 예시 값 |
|---|---|---|---|
| aiReadableContent.notes | string, 생략 가능 / 미설정, 빈 출력 | 조건부 적용: 공개 텍스트에 Markdown 사이트 설명을 넣습니다. 빈 문자열·공백은 출력하지 않습니다. 본문 대체나 특정 AI의 비공개 프롬프트가 아닙니다. | ‘이 사이트는 개인 학습 노트이며 계속 수정될 수 있습니다.’ |
| aiReadableContent.links | { label: string; href: string }[], 생략 가능 / 미설정, 빈 목록 | 조건부 적용: 공개 링크를 추가합니다. 배열 전체 대체이며 []는 비웁니다. 공개 개수 한도는 없고 목표 내용을 자동 수집하지 않습니다. | [{ label: ‘프로젝트 홈페이지’, href: ‘https://example.com/project/’ }] |
| aiReadableContent.links[].label | string, 필수 / 없음 | 조건부 적용: trim 후 비어 있지 않아야 합니다. 출력 시 줄바꿈은 공백으로, 역슬래시·대괄호는 이스케이프합니다. 목표 페이지 제목을 가져오지 않습니다. | ‘프로젝트 홈페이지’ |
| aiReadableContent.links[].href | string, 필수 / 없음 | 조건부 적용: 비어 있지 않아야 하며 공개 루트 URL로 해석합니다. HTTP(S)만 허용하고 사용자 이름·비밀번호는 안 됩니다. 잘못된 값은 오류이며 존재·접근 가능 여부는 검증하지 않습니다. | ‘https://example.com/project/’ |
notes·links에 일반 문자 길이 설정은 없으며 타입을 따라야 합니다. 잘못된 타입, 빈 링크 이름, 비웹 프로토콜, 자격 증명 링크는 빌드를 막을 수 있습니다. 보충의 명령을 실행하거나 모델로 설명을 생성하지 않습니다.
Markdown과 상대 링크 처리
notes는 Markdown 텍스트·형식·코드 예시를 유지합니다. 해석된 Markdown 링크, 이미지, 참조 정의의 목표는 절대 주소로 바꾸며 같은 HTTP(S)·자격 증명 없음 검증을 적용합니다. 코드 블록 속 링크 예시는 실제 목표로 재작성하지 않습니다. 임의 HTML의 완전한 검증기나 스크린샷 서비스는 아닙니다.
기준은 Astro base를 포함한 사이트 공개 루트 URL입니다. 현재 글 URL이나 언어 디렉터리가 아닙니다. 공개 루트가 https://example.com/project/일 때:
| href 또는 Markdown 목표 | 결과 |
|---|---|
| zh/blog/ | https://example.com/project/zh/blog/ |
| /zh/blog/ | https://example.com/zh/blog/ |
| https://docs.example.com/guide/ | 해당 외부 URL 유지 |
하위 경로 배포에서 단일 / 시작은 도메인 루트 기준이며 /project/를 자동 유지하지 않습니다. 음악 등 루트 경로에 BASE_URL을 추가하는 규칙과 혼용하지 마세요. mailto:, tel:, file:, javascript: 등은 추가 링크에 사용하지 않습니다. 본문 연락 링크는 자체 내보내기 규칙이 있으므로 보충도 같은 프로토콜을 받는 것은 아닙니다.
전역 예시
aiReadableContent: {
notes: '이 사이트는 개인 학습 노트이며 계속 수정될 수 있습니다.자세한 내용은 [글 목록](ko/blog/)을 참고하세요.',
links: [
{ label: '프로젝트 홈페이지', href: 'https://example.com/project/' },
],
},
언어별 aiReadableContent 덮어쓰기
전체 접두사는 i18n.locales.<locale>.aiReadableContent이며 동일한 선택적 MachineReadableSupplement, 기본 미설정입니다. 역할은 전역과 같지만 생략 시 필드별로 전역을 상속합니다.
| 상대 필드 | 타입 / 기본값 | 역할·제한 | 예시 값 |
|---|---|---|---|
| notes | string, 생략 가능 / 전역 notes 상속 | 조건부 적용: 해당 언어의 공개 보충입니다. ‘’·공백은 명시적으로 비우며 다른 언어로 대체하지 않습니다. | ‘중국어 콘텐츠는 계속 업데이트합니다.’ |
| links | { label: string; href: string }[], 생략 가능 / 전역 links 상속 | 조건부 적용: 전체 추가 링크 배열을 대체하고 []로 비웁니다. 전역에 덧붙이지 않습니다. | [] |
| links[].label | string, 필수 / 없음 | 사용자 항목이 있으면 필수이며 검증·이스케이프는 전역과 같습니다. | ‘중국어 글’ |
| links[].href | string, 필수 / 없음 | 사용자 항목이 있으면 필수이며 기준은 계속 공개 루트이지 언어 디렉터리가 아닙니다. | ‘zh/blog/’ |
중국어 간체 설명만 바꾸고 추가 링크를 숨기는 예시입니다.
i18n: {
locales: {
zh: {
aiReadableContent: {
notes: '中文内容持续更新。',
links: [],
},
},
},
},
notes만 덮어쓰면 전역 links를 상속하고 {}는 둘 다 상속합니다. undefined는 무시하며 비우기 명령이 아닙니다. meta.fallback을 따르거나 영어 등 대체 언어 보충을 복사하지 않습니다. 언어 사전을 참고하세요.
루트 llms.txt는 항상 전역 보충을 사용합니다. 언어 덮어쓰기는 그 언어의 인덱스, 모음, 개별 Markdown에 사용합니다. 따라서 전역 보충이 잘못되었다면 모든 언어에서 비워도 우회할 수 없으며 루트 인덱스는 계속 처리합니다.
어떤 공개 산출물에 들어가나요?
아래 경로는 사이트 공개 루트 기준이며 하위 배포에는 접두사를 더합니다. 실제 내보낼 콘텐츠가 있는 언어만 인덱스·모음을 만들며 보충 설정이 글을 새로 만들지는 않습니다.
| 산출물 | 보충 위치·내용 |
|---|---|
| llms.txt | 루트 입구입니다. 전역 notes는 언어 디렉터리 앞, links는 추가 링크 영역입니다. 내보낼 콘텐츠가 없어도 전역 보충은 포함할 수 있습니다. |
<locale>/llms.txt |
언어 입구입니다. 덮어쓴 설명·링크를 사용하며 Articles / Fragments / About으로 기존 공개 문서를 분류합니다. |
<locale>/llms-full.txt |
해당 언어의 공개 전문 모음이며 문서 본문 모음 앞에 설명·추가 링크가 있습니다. |
| 글의 index.md 등 Markdown | 본문 뒤 구분선, 사이트 보충 표식, 유효 설명을 추가하며 작성자 본문과 섞지 않습니다. |
<locale>/about/index.md |
공개 소개·연락처와 현재 접근 가능한 AI 정적 텍스트 패널입니다. 끝에 같은 규칙으로 보충하며 전체 도구 설정을 내보내지 않습니다. |
<locale>/fragments/index.md |
페이지를 합친 공개 콘텐츠와 안정적 ID 링크입니다. 끝에 보충하며 페이지별로 전문 모음을 중복 생성하지 않습니다. |
개별 Markdown 경로는 빌드 HTML 위치가 정하며 index.html은 index.md에 대응합니다. Astro 출력 형식이 다를 수 있으므로 경로를 직접 만들어 생성 파일을 덮어쓰지 마세요. 내보낸 페이지에는 Markdown·해당 언어 인덱스의 발견 링크도 붙습니다.
내보내기는 표식이 있고 공개 색인이 가능하며 canonical이 같은 출처인 글, About, Fragments만 처리합니다. 기본 홈, 목록, Decoder 폼, 댓글 iframe은 글로 내보내지 않습니다. 본문 링크·코드·표는 빌드 결과에서 변환하며 렌더링되지 않은 임의 설정을 묶어 공개하지 않습니다. About AI 팝업은 이미 열 수 있는 정적 문구이므로 입력 전 공개 자료로 취급하세요.
search: false는 Pagefind만 제외하며 이 산출물은 제외하지 않습니다. notes/links를 비워도 본문 내보내기는 유지합니다. aiReadableContent.enabled, 글 제외, AI 서비스 주소, 모델 매개변수, API key 필드는 없습니다. 읽을 수 있는 공개 자료이며 모델의 수집·인용·순위 향상을 보장하지 않습니다.
생성기는 자신의 이전 목록에 속하지 않는 같은 이름의 파일을 보호하며 충돌 시 오류입니다. public이나 빌드 디렉터리에 같은 llms.txt·Markdown 경로를 직접 만들지 마세요. 소스 설정을 고친 뒤 재빌드하고 전체 산출물을 배포하세요. 빌드 성공은 온라인 갱신이나 모델 읽기 완료의 증거가 아닙니다.
관련 설정과 현재 범위
- 공개 주소는 site.url, 환경 덮어쓰기, Astro 공개 base가 함께 결정합니다. 루트 제목·설명은 현재 사이트 맥락을 사용합니다. 배포 가이드를 참고하고 보충 문구의 주소 변경이 canonical을 바꾼다고 기대하지 마세요.
- 언어 스위치는 표준 페이지 생성을 제어하며 이전 호스팅 파일을 자동 삭제하지 않습니다. 보충은 번역을 만들지 않습니다. 언어 사전을 참고하세요.
- GA4는 통계 로드만 제어하며 검색, RSS, 기계 읽기를 제어하지 않습니다. 정적 보충에도 자체 버튼, 번역 문구, 통계 스위치는 없습니다.
- GA4 ID와 보충 필드는 모두 소비 위치가 있으며 추가로 입력할 구식 필드는 없습니다. 구형 adapter의 통계 분기 없음은 비활성 호환 처리일 뿐 활성화 방법이 아닙니다.
수정 후 재빌드·재배포해야 합니다. 통계는 브라우저 차단, 네트워크, 통계 측 설정에 영향을 받으며 로컬 텍스트 생성 검사로 온라인 통계 확인을 대신할 수 없습니다. 설정 사전 시작 페이지에서 다른 모듈을 보세요.