버전: v2

GitHub Pages

GitHub Pages를 이용하면 브라우저를 벗어나지 않고도 무료로 데이터베이스를 개설할 수 있습니다. 서버를 임대할 필요도, FTP 클라이언트도, 빌드 과정도, 설치할 프로그램도 없습니다. 아직 서버가 없다면 사이트를 가장 빠르게 배포할 수 있는 방법입니다.

개요

이 방식은 CDN 버전의 modernGraphTool을 GitHub이 호스팅해 주는 것입니다. 사이트에 필요한 모든 파일 — index.html, config.js, theme.css, data/, assets/ — 이 이미 들어 있는 템플릿 저장소를 복사하고, GitHub Pages를 활성화한 다음, 예시 측정 데이터를 본인의 것으로 교체하면 됩니다. 애플리케이션 코드는 jsDelivr에서 불러와 스스로 업데이트되므로, 저장소에는 항상 본인의 콘텐츠만 남습니다.

모든 작업은 github.com 웹 인터페이스에서 가능합니다. 데이터베이스가 커지면 Git과 로컬 편집기를 사용하는 것이 편리하지만, 여기에서 소개하는 내용을 따라가는데 필수인 것은 없습니다.

템플릿 저장소: potatosalad775/modernGraphTool_site

설치

1. 템플릿 복사하기

potatosalad775/modernGraphTool_site를 열고 Use this template → Create a new repository를 클릭합니다.

이 때 저장소 이름을 입력하게 되는데, 이 이름이 사이트 주소를 결정합니다. 아래 두 가지 모두 동작하며, 설정을 다르게 할 필요는 없습니다:

저장소 이름	사이트 주소	비고
`my-squig` (자유롭게)	`your_username.github.io/my-squig/`	프로젝트 사이트. 이름은 원하는 대로 지어도 됩니다.
`your_username.github.io`	`your_username.github.io/`	사용자 사이트. 계정당 하나만 만들 수 있습니다.

저장소는 Public으로 설정하세요 — 무료 계정에서 GitHub Pages는 공개 저장소를 요구합니다.

어떤 이름을 골라야 하나요?

your_username.github.io 이름의 저장소가 존재하지 않고, modernGraphTool 데이터베이스를 주력으로 배포할 예정이라면 사용자 사이트로 배포하는 것을 권장합니다. 주소가 짧아 공유하기 편합니다. 그렇지 않다면 평범한 이름을 쓰세요. 실질적인 차이는 경로 한 칸이 늘어나는 것뿐입니다. 나중에 저장소 이름을 바꿔도 사이트는 그대로 동작합니다. 기준 경로가 설정 파일에 기록되는 대신 실행 시점에 감지되기 때문입니다. 기준 경로를 참고하세요.

2. GitHub Pages 켜기

새 저장소에서 Settings → Pages로 이동합니다. Build and deployment 항목에서:

Source: Deploy from a branch
Branch: main, 폴더는 / (root)

Save를 누릅니다.

1분 정도 기다린 뒤 페이지를 새로고침하면 상단에 사이트 주소가 표시됩니다. 열어 보면 예시 측정 데이터가 들어간 그래프 도구가 보일 것입니다.

이 시점에서 사이트 개설 과정은 마무리됩니다. 이후에는 예시 데이터를 본인의 것으로 바꾸는 작업만이 남았습니다.

GitHub Actions는 필요 없습니다

템플릿은 순수한 정적 파일이라 Pages가 브랜치를 그대로 배포합니다. Actions를 켤 필요도, 빌드가 끝나기를 기다리거나 실패를 디버깅할 일도 없습니다. 유일한 지연은 커밋 후 최대 1분 정도 걸리는 Pages 자체의 재배포입니다.

3. 측정 데이터 업로드

측정 파일은 CrinGraph가 쓰는 것과 같은, 두 개의 열로 이루어진 일반 텍스트 형식입니다. 원본 측정 결과에서 시작한다면 측정 데이터 전처리를 참고하세요.

저장소에서 data/phones/ 폴더를 엽니다.
Add file → Upload files를 누르고 .txt 파일을 끌어다 놓습니다.
Commit changes를 누릅니다.

파일 이름은 도구가 기대하는 형식을 따르세요 — 좌우 한 쌍이라면 Brand Model L.txt와 Brand Model R.txt입니다. 본인 파일을 다 올렸다면 예시 파일은 지우면 됩니다. 파일을 열고 휴지통 아이콘을 누르거나, 폴더 화면에서 여러 개를 선택해 삭제할 수 있습니다.

브라우저 업로드 제한

웹 업로더는 한 번에 최대 100개 파일, 파일당 25 MB까지 받습니다. 측정 파일은 매우 작으므로 개수 제한에 먼저 도달할 가능성이 큽니다. 이 경우에는 파일을 여러 차례 나눠서 올리면 됩니다. 기존의 큰 데이터베이스를 옮기는 중이라면 저장소를 클론해서 폴더를 한 번에 커밋하는 편이 훨씬 수월합니다. 로컬에서 작업하기를 참고하세요.

4. `phone_book.json` 편집

data/phone_book.json은 업로드한 파일들을 사용자가 둘러보는 브랜드·모델 목록으로 만들어 주는 파일입니다. 저장소에서 파일을 열고 연필 아이콘을 눌러 편집합니다:

[
	{
		"name": "Your Brand",
		"phones": [{ "name": "Model One", "file": "Your Brand Model One" }]
	}
]

file 값은 파일 이름에서 L.txt / R.txt 부분을 뺀 것입니다. 변형(variants)과 샘플 세트를 포함한 전체 스키마는 데이터 관리에 있습니다.

JSON을 직접 손으로 고치면 실수하기 쉽고, 쉼표 하나만 빠져도 기기 목록이 통째로 비어 버립니다. phone_book.json 편집기는 이 파일을 위한 시각적 편집기입니다. 저장소의 파일을 불러와 편집하고 내보낸 뒤, 결과를 다시 붙여 넣으면 됩니다.

5. 커스터마이징

config.js — 사이트 제목, 초기 기기와 타겟, 정규화 기본값을 비롯한 모든 설정. 페이지 커스터마이징을 참고하거나, 설정 편집기로 시각적으로 만들 수 있습니다.
theme.css — 그래프와 인터페이스 색상. 테마 항목 또는 테마 생성기를 참고하세요.
index.html — 브라우저 탭 제목과 링크 미리보기에 쓰이는 설명. 수정할 부분이 주석으로 표시되어 있습니다.
assets/ — 파비콘과 로고 이미지.

기준 경로

프로젝트 사이트는 저장소 이름을 딴 하위 디렉터리 — username.github.io/my-squig/ — 에서 서빙되며, 애플리케이션이 이 접두사를 알고 있어야 합니다. 모르면 첫 화면은 뜨지만 공유 링크가 전부 404가 납니다. 이는 CDN 배포에서 가장 흔한 실수이고, GitHub Pages에서는 거의 모든 사람에게 해당됩니다.

템플릿이 이를 대신 처리합니다. 템플릿의 index.html에는 로더가 시작되기 전에 URL에서 접두사를 읽어 내는 짧은 스크립트가 들어 있습니다:

var seg = location.pathname.split('/').filter(Boolean)[0];
cdn.BASE_PATH = seg && !/\.html?$/i.test(seg) ? '/' + seg : '';

이 스크립트는 *.github.io 호스트에서만, 그리고 config.js가 CDN_MODE.BASE_PATH를 지정하지 않은 경우에만 동작합니다. 덕분에 두 저장소 형태 모두 설정 없이 올바르게 동작하고, 저장소 이름을 바꿔도 사이트가 깨지지 않습니다:

URL	감지된 기준 경로
`username.github.io/my-squig/`	`/my-squig`
`username.github.io/my-squig/?share=…`	`/my-squig`
`username.github.io/`	`''` (루트)

직접 BASE_PATH를 지정해야 하는 경우는 하나입니다: 사이트를 하위 폴더에서 서빙하는 커스텀 도메인입니다. 호스트 이름이 더 이상 *.github.io가 아니므로 자동 감지가 멈춥니다. 다만 프로젝트 사이트에 연결한 커스텀 도메인은 어차피 도메인 루트에서 서빙되며, 이 경우에는 BASE_PATH를 비워 두는 것이 맞습니다. 리버스 프록시 뒤에 두었거나 더 큰 사이트의 하위 폴더에 넣은 경우에만 config.js에 명시하세요:

CDN_MODE: {
  BASE_PATH: '/headphones',
  MAJOR_VERSION: 2,
},

끝에 슬래시는 붙이지 않습니다. 어느 쪽이든 확인 방법은 같습니다. 사이트를 열어 기기를 하나 추가하고, 공유 링크를 복사해 새 탭에서 열어 보세요. 같은 기기가 뜬다면 기준 경로가 맞는 것입니다.

앱 업데이트

할 일이 없습니다. 애플리케이션은 jsDelivr에서 불러오며, 고정해 둔 메이저 버전 안에서 새 릴리스를 자동으로 받아 갑니다. CDN 배포에서 설명하는 것과 같은 방식입니다.

새 메이저 버전이 나오고 옮겨 갈 준비가 되면 config.js의 MAJOR_VERSION을 고쳐 커밋하면 됩니다. 이 배포 방식이 요구하는 업데이트 작업은 그것뿐입니다.

템플릿이 갱신되어도 내 저장소는 그대로입니다

modernGraphTool의 기본값이 바뀌면 템플릿 저장소도 함께 갱신되지만, "Use this template"으로 만든 저장소는 완전히 독립적입니다. 업스트림 연결이 없으므로 그쪽에서 내 설정이나 측정 데이터를 덮어쓸 일은 없습니다. 다시 복사해 올 필요도 없습니다. 애플리케이션 코드는 템플릿이 아니라 CDN에서 오기 때문입니다.

커스텀 도메인

보유한 도메인이 있다면 username.github.io 대신 그 도메인으로 사이트를 서빙할 수 있습니다.

DNS 제공자에서 도메인을 GitHub Pages로 향하게 합니다 — 서브도메인이면 username.github.io를 가리키는 CNAME 레코드, 최상위 도메인이면 GitHub Pages IP를 가리키는 A 레코드입니다. 최신 주소는 GitHub의 커스텀 도메인 문서에 있습니다.
저장소에서 Settings → Pages → Custom domain에 도메인을 입력하고 Save를 누릅니다. 이때 저장소에 CNAME 파일이 커밋되는데, 지우지 마세요.
DNS 확인이 끝나면 Enforce HTTPS를 켭니다.

커스텀 도메인은 사이트를 도메인 루트에서 서빙하므로 BASE_PATH는 비워 둡니다. 예외는 기준 경로를 참고하세요.

로컬에서 작업하기 (선택)

위 내용은 모두 브라우저에서 처리할 수 있습니다. 데이터베이스가 커져서 나눠 올리기가 번거로워지면, 저장소를 클론할 만합니다:

git clone https://github.com/username/my-squig.git
cd my-squig
# 측정 파일 복사, config.js 수정, ...
git add .
git commit -m "Add new measurements"
git push

푸시 후 1분 안에 Pages가 다시 배포합니다.

푸시 전에 결과를 미리 보려면 아무 정적 파일 서버로 폴더를 서빙하고 루트에서 열면 됩니다:

npx serve .

localhost에서는 기준 경로 자동 감지가 동작하지 않습니다. 필요하지도 않습니다. 로컬에서는 루트에서 서빙하게 되고, 로더가 알아서 빈 기준 경로로 해석하기 때문입니다.

문제 해결

Pages를 켜자마자 404가 뜹니다

원인: Pages의 첫 배포가 아직 끝나지 않았습니다.

해결: 1분쯤 기다렸다가 새로고침하세요. 계속된다면 Settings → Pages를 다시 확인합니다. 브랜치가 main, 폴더가 / (root)여야 합니다.

첫 화면은 뜨는데 공유 링크가 404입니다

원인: 기준 경로가 제대로 해석되지 않고 있습니다. *.github.io에서는 일어나지 않아야 하는 일이며, 보통은 손으로 지정한 CDN_MODE.BASE_PATH가 실제 경로와 맞지 않는 경우입니다. 명시된 값이 자동 감지보다 우선합니다.

해결: config.js의 BASE_PATH를 주석 처리해 템플릿이 감지하도록 두세요. 커스텀 도메인이라면 기준 경로를 참고하세요.

목록에는 기기가 보이는데 그래프가 비어 있습니다

원인: phone_book.json의 file 값이 실제 파일 이름과 다릅니다.

해결: 한 글자씩 비교해 보세요. 대소문자와 공백을 구분하며, L.txt 부분은 포함하지 않아야 합니다. 브라우저 네트워크 탭에서 404가 난 요청을 보면 어떤 경로를 찾았는지 정확히 알 수 있습니다.

화면이 하얗게 비어 있습니다

원인: 대부분 config.js의 문법 오류입니다.

해결: 브라우저 콘솔(F12)을 여세요. 쉼표 누락이나 닫히지 않은 따옴표를 줄 번호와 함께 알려 줍니다. 직접 디버깅하고 싶지 않다면 설정 편집기가 올바른 파일을 만들어 줍니다.

수정한 내용이 반영되지 않습니다

원인: Pages 재배포 지연 또는 브라우저 캐시.

해결: 커밋 후 1분 정도 기다린 다음 강력 새로고침(Ctrl+Shift+R / Cmd+Shift+R)을 하세요. 저장소의 Actions 탭에서 Pages 빌드가 끝났는지 확인할 수 있습니다.

앱은 뜨는데 CSS나 이미지가 404입니다

원인: .nojekyll 파일이 없습니다. 이 파일이 없으면 GitHub Pages가 Jekyll을 실행하는데, Jekyll은 이름이 밑줄로 시작하는 파일과 폴더를 무시합니다.

해결: 저장소 루트에 .nojekyll이 그대로 있는지 확인하세요. 템플릿에 포함되어 있으며, 지워졌다면 빈 파일로 다시 만들면 됩니다.

엉뚱한 주소에서 GitHub의 404 페이지가 나옵니다

정상입니다. 애플리케이션은 사이트 경로의 루트에 있고 모든 상태를 쿼리 파라미터로 받으므로, 잘못 입력한 주소에서만 발생합니다. 공유 링크에는 영향이 없습니다.

개요​

추천 대상​

설치​

1. 템플릿 복사하기​

2. GitHub Pages 켜기​

3. 측정 데이터 업로드​

4. phone_book.json 편집​

5. 커스터마이징​

기준 경로​

앱 업데이트​

커스텀 도메인​

로컬에서 작업하기 (선택)​

문제 해결​

Pages를 켜자마자 404가 뜹니다​

첫 화면은 뜨는데 공유 링크가 404입니다​

목록에는 기기가 보이는데 그래프가 비어 있습니다​

화면이 하얗게 비어 있습니다​

수정한 내용이 반영되지 않습니다​

앱은 뜨는데 CSS나 이미지가 404입니다​

엉뚱한 주소에서 GitHub의 404 페이지가 나옵니다​

개요

추천 대상

설치