네오시티(Neocities)에 웹사이트를 하나 올린 다음에는 파일을 고치는 방식, 공개할 범위, 오래 남길 주소를 함께 다루게 된다. 이 문서는 개인 웹사이트를 작업실과 작은 출판물로 운영할 때 쓸 만한 기술을 모은다.
작업 폴더와 공개 폴더
- 완성된 파일만 내보내기: 원고·원본 이미지·설정은 작업 폴더에 두고, 공개할 HTML·CSS·이미지는
public/같은 별도 폴더에 모은다. 작품 파일과 납품 파일을 나누는 것과 같은 판단이다. - 생성은 내 컴퓨터에서: 정적 사이트 생성기로 작품별 웹 페이지와 목차를 미리 만들고 결과물만 올릴 수 있다. 네오시티는 정적 HTML 호스팅이므로, 서버에서 PHP나 데이터베이스가 작동해야 하는 프로그램을 그대로 옮기는 용도로 고르지 않는다. (네오시티 소개, MDN의 정적·동적 웹사이트 구분)
- 공개본도 한 벌 보관하기: 배포한 폴더를 날짜별로 남기면 이전 판의 파일을 다시 올릴 수 있다. 원본 저장소의 변경 기록과 실제 공개한 파일의 기록을 구분한다. 정적 웹사이트의 복원 연습에는 빠진 파일과 이미 바뀐 주소까지 포함할 수 있다.
터미널에서 배포하기
루비가 설치된 환경에서는 gem install neocities로 공식 CLI를 설치한다. neocities info를 실행하고 설정에서 발급한 API 키를 입력하면 인증 정보를 저장한다. 공개 폴더를 public/로 정했다면 다음 순서로 사용한다. (공식 CLI 안내)
neocities push --dry-run public
neocities push public- 첫 줄은 업로드 예정 파일을 확인하고, 둘째 줄은 실제로 웹사이트를 바꾼다. 실행 위치에
public/폴더가 있어야 한다. - 변경되지 않은 파일은 건너뛴다. 출력의
EXISTS는 같은 파일이 이미 있다는 뜻이다. - 기본
push는 서버의 나머지 파일을 지우지 않는다. 로컬에서 지운 초안이 서버에서도 사라졌다고 생각하면 안 된다. 삭제 동기화 옵션--prune은 지울 파일을 확인하고 백업한 뒤 선택한다. - 업로드 폴더 루트의
.gitignore를 참고하지만, 제외 규칙만 믿기보다 공개 폴더 안을 직접 확인하는 편이 분명하다.
자동화는 변경된 파일부터
- 배포용 비밀: 자동화 환경의 비밀 저장소에서
NEOCITIES_API_KEY를 제공하면 CLI를 대화식 입력 없이 실행할 수 있다. 키를 공개 HTML·자바스크립트·저장소에 넣지 않는다. (CLI 자동화 안내) - 비교와 전송: 직접 배포 도구를 만든다면
/api/upload_hash로 파일 경로와 SHA-1을 보내 비교한다. 응답의true는 같은 내용,false는 업로드할 필요가 있다는 뜻이다./api/upload는 한 요청에 여러 파일을 보낼 수 있다. (API 문서) - 경로는 따로 지정: 업로드 API의 폼 필드 이름이 서버의 저장 경로가 된다. 내 컴퓨터의 파일 이름과 공개할 이름을 다르게 정할 수 있으므로, 전송 전 둘의 대응을 확인한다.
- 주기 조절: 공식 API 안내는 반복 갱신을 10분에 한 번 수준으로 제한하고 과도한 병렬 요청을 피하라고 권한다. 변경이 없는데 활동 표시를 만들려고 다시 올리는 자동화는 두지 않는다.
작품 목록을 데이터로 다루기
- 한 자료에서 여러 화면 만들기: 작품 목록을 데이터로 만들기처럼 제목·연도·이미지 경로를 JSON으로 관리하면 연도순 목록, 작품별 화면, 이미지 목차를 같은 자료에서 생성할 수 있다. 네오시티의 허용 파일 형식에는 JSON·CSV·SVG·WOFF2도 포함된다. (허용 파일 형식)
- 출판 시점에 조립하기: 방문할 때마다 JSON을 읽는 대신, 배포 전에 HTML 목록을 만들 수도 있다. 작품 설명을 읽는 데 자바스크립트가 반드시 필요해지는지 판단하고 방식부터 고른다.
- 웹 브라우저에서 읽기:
fetch('/data/works.json')처럼 같은 웹사이트의 자료를 읽는다면 경로와 응답 상태를 확인한다.file://로 파일을 여는 환경은 출처를 다루는 방식이 달라 오류가 날 수 있으므로, 로컬 HTTP 서버에서도 확인한다. (MDN의 동일 출처 정책) - 저장과 접수 구별하기:
localStorage에 저장한 메모는 해당 출처와 웹 브라우저의 저장 공간에 남는다. 운영자에게 전달된 신청서나 모든 방문자가 공유하는 방명록은 아니다. 실제 접수가 필요하면 신청 폼은 질문의 순서다에서 입력 이후의 처리를 살핀다. (MDN의 localStorage)
다른 웹사이트와 연결할 때
- 들어오는 요청과 나가는 요청: 다른 웹사이트가 내 JSON을 읽는 문제와, 내 웹 페이지가 외부 API를 읽는 문제는 방향이 다르다. 전자는 내 응답의 CORS 허용을, 후자는 상대 서버의 CORS와 내 웹 페이지의 콘텐츠 보안 정책을 함께 살핀다. (MDN의 CORS, MDN의 콘텐츠 보안 정책)
- 요금제의 경계: 공식 후원 플랜에는 사용자 지정 도메인, CORS 지원, 더 완화된 콘텐츠 보안 정책이 안내되어 있다. 후원하면 모든 외부 API를 읽을 수 있다는 뜻은 아니다. 상대 서버가 허용하는 출처와 인증 조건도 남는다. (네오시티 플랜 비교)
- 주소를 바꾸면 저장 공간도 달라진다: 기본 네오시티 주소에서 개인 도메인으로 옮기면 웹 브라우저가 판단하는 출처가 달라진다. 이전 주소의
localStorage가 새 주소로 자동 이사하지는 않는다. (MDN의 동일 출처 정책)
주소와 판을 오래 유지하기
- 작품 주소와 파일 버전 나누기: 작품의 HTML 주소는 유지하고, 바뀐 이미지나 CSS에는
poster-v2.webp처럼 새 이름을 주는 방식을 고려한다. 새 자산을 먼저 올리고 이를 가리키는 HTML을 나중에 올리면 없는 파일을 가리키는 시간을 줄일 수 있다. - 배포 묶음을 구별하기: 옛 HTML을 열어둔 방문자가 있을 수 있다. 새 판을 올리자마자 옛 자산을 모두 삭제하기보다 남길 기간을 정한다. 여러 파일의 업로드를 웹사이트 전체가 한순간에 교체되는 배포로 가정하지 않는다.
- 목록을 백업으로 착각하지 않기:
/api/list는 경로·크기·해시 등을 반환한다. 파일 내용은/api/download로 별도로 받아야 한다. 파일명만 적힌 장부로는 작품을 다시 열 수 없다. (API 문서)