[[네오시티]](Neocities)에 웹사이트를 하나 올린 다음에는 파일을 고치는 방식, 공개할 범위, 오래 남길 주소를 함께 다루게 된다. 이 문서는 개인 웹사이트를 작업실과 작은 출판물로 운영할 때 쓸 만한 기술을 모은다.

## 작업 폴더와 공개 폴더

- **완성된 파일만 내보내기:** 원고·원본 이미지·설정은 작업 폴더에 두고, 공개할 HTML·CSS·이미지는 `public/` 같은 별도 폴더에 모은다. [[작품 파일과 납품 파일]]을 나누는 것과 같은 판단이다.
- **생성은 내 컴퓨터에서:** [[정적 사이트 생성기]]로 작품별 웹 페이지와 목차를 미리 만들고 결과물만 올릴 수 있다. 네오시티는 정적 HTML 호스팅이므로, 서버에서 PHP나 데이터베이스가 작동해야 하는 프로그램을 그대로 옮기는 용도로 고르지 않는다. ([네오시티 소개](https://neocities.org/about), [MDN의 정적·동적 웹사이트 구분](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Server-side/First_steps/Client-Server_overview))
- **공개본도 한 벌 보관하기:** 배포한 폴더를 날짜별로 남기면 이전 판의 파일을 다시 올릴 수 있다. 원본 저장소의 변경 기록과 실제 공개한 파일의 기록을 구분한다. [[정적 웹사이트의 복원 연습]]에는 빠진 파일과 이미 바뀐 주소까지 포함할 수 있다.

## 터미널에서 배포하기

루비가 설치된 환경에서는 `gem install neocities`로 공식 CLI를 설치한다. `neocities info`를 실행하고 설정에서 발급한 API 키를 입력하면 인증 정보를 저장한다. 공개 폴더를 `public/`로 정했다면 다음 순서로 사용한다. ([공식 CLI 안내](https://neocities.org/cli))

```sh
neocities push --dry-run public
neocities push public
```

- 첫 줄은 업로드 예정 파일을 확인하고, 둘째 줄은 실제로 웹사이트를 바꾼다. 실행 위치에 `public/` 폴더가 있어야 한다.
- 변경되지 않은 파일은 건너뛴다. 출력의 `EXISTS`는 같은 파일이 이미 있다는 뜻이다.
- 기본 `push`는 서버의 나머지 파일을 지우지 않는다. 로컬에서 지운 초안이 서버에서도 사라졌다고 생각하면 안 된다. 삭제 동기화 옵션 `--prune`은 지울 파일을 확인하고 백업한 뒤 선택한다.
- 업로드 폴더 루트의 `.gitignore`를 참고하지만, 제외 규칙만 믿기보다 공개 폴더 안을 직접 확인하는 편이 분명하다.

## 자동화는 변경된 파일부터

- **배포용 비밀:** 자동화 환경의 비밀 저장소에서 `NEOCITIES_API_KEY`를 제공하면 CLI를 대화식 입력 없이 실행할 수 있다. 키를 공개 HTML·자바스크립트·저장소에 넣지 않는다. ([CLI 자동화 안내](https://neocities.org/cli))
- **비교와 전송:** 직접 배포 도구를 만든다면 `/api/upload_hash`로 파일 경로와 SHA-1을 보내 비교한다. 응답의 `true`는 같은 내용, `false`는 업로드할 필요가 있다는 뜻이다. `/api/upload`는 한 요청에 여러 파일을 보낼 수 있다. ([API 문서](https://neocities.org/api))
- **경로는 따로 지정:** 업로드 API의 폼 필드 이름이 서버의 저장 경로가 된다. 내 컴퓨터의 파일 이름과 공개할 이름을 다르게 정할 수 있으므로, 전송 전 둘의 대응을 확인한다.
- **주기 조절:** 공식 API 안내는 반복 갱신을 10분에 한 번 수준으로 제한하고 과도한 병렬 요청을 피하라고 권한다. 변경이 없는데 활동 표시를 만들려고 다시 올리는 자동화는 두지 않는다.

## 작품 목록을 데이터로 다루기

- **한 자료에서 여러 화면 만들기:** [[작품 목록을 데이터로 만들기]]처럼 제목·연도·이미지 경로를 JSON으로 관리하면 연도순 목록, 작품별 화면, 이미지 목차를 같은 자료에서 생성할 수 있다. 네오시티의 허용 파일 형식에는 JSON·CSV·SVG·WOFF2도 포함된다. ([허용 파일 형식](https://neocities.org/site_files/allowed_types))
- **출판 시점에 조립하기:** 방문할 때마다 JSON을 읽는 대신, 배포 전에 HTML 목록을 만들 수도 있다. 작품 설명을 읽는 데 자바스크립트가 반드시 필요해지는지 판단하고 방식부터 고른다.
- **웹 브라우저에서 읽기:** `fetch('/data/works.json')`처럼 같은 웹사이트의 자료를 읽는다면 경로와 응답 상태를 확인한다. `file://`로 파일을 여는 환경은 출처를 다루는 방식이 달라 오류가 날 수 있으므로, 로컬 HTTP 서버에서도 확인한다. ([MDN의 동일 출처 정책](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy))
- **저장과 접수 구별하기:** `localStorage`에 저장한 메모는 해당 출처와 웹 브라우저의 저장 공간에 남는다. 운영자에게 전달된 신청서나 모든 방문자가 공유하는 방명록은 아니다. 실제 접수가 필요하면 [[신청 폼은 질문의 순서다]]에서 입력 이후의 처리를 살핀다. ([MDN의 localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage))

## 다른 웹사이트와 연결할 때

- **들어오는 요청과 나가는 요청:** 다른 웹사이트가 내 JSON을 읽는 문제와, 내 웹 페이지가 외부 API를 읽는 문제는 방향이 다르다. 전자는 내 응답의 CORS 허용을, 후자는 상대 서버의 CORS와 내 웹 페이지의 콘텐츠 보안 정책을 함께 살핀다. ([MDN의 CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS), [MDN의 콘텐츠 보안 정책](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP))
- **요금제의 경계:** 공식 후원 플랜에는 사용자 지정 도메인, CORS 지원, 더 완화된 콘텐츠 보안 정책이 안내되어 있다. 후원하면 모든 외부 API를 읽을 수 있다는 뜻은 아니다. 상대 서버가 허용하는 출처와 인증 조건도 남는다. ([네오시티 플랜 비교](https://neocities.org/supporter))
- **주소를 바꾸면 저장 공간도 달라진다:** 기본 네오시티 주소에서 개인 도메인으로 옮기면 웹 브라우저가 판단하는 출처가 달라진다. 이전 주소의 `localStorage`가 새 주소로 자동 이사하지는 않는다. ([MDN의 동일 출처 정책](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy))

## 주소와 판을 오래 유지하기

- **작품 주소와 파일 버전 나누기:** 작품의 HTML 주소는 유지하고, 바뀐 이미지나 CSS에는 `poster-v2.webp`처럼 새 이름을 주는 방식을 고려한다. 새 자산을 먼저 올리고 이를 가리키는 HTML을 나중에 올리면 없는 파일을 가리키는 시간을 줄일 수 있다.
- **배포 묶음을 구별하기:** 옛 HTML을 열어둔 방문자가 있을 수 있다. 새 판을 올리자마자 옛 자산을 모두 삭제하기보다 남길 기간을 정한다. 여러 파일의 업로드를 웹사이트 전체가 한순간에 교체되는 배포로 가정하지 않는다.
- **목록을 백업으로 착각하지 않기:** `/api/list`는 경로·크기·해시 등을 반환한다. 파일 내용은 `/api/download`로 별도로 받아야 한다. 파일명만 적힌 장부로는 작품을 다시 열 수 없다. ([API 문서](https://neocities.org/api))

## 기타 등등

- CLI의 `logout`은 컴퓨터에 저장된 API 키를 지운다. 이미 복사된 키까지 무효화하려면 웹사이트 설정에서 키를 재발급해야 한다. [출처](https://neocities.org/cli)
- 업로드할 수 있는 확장자 목록에는 `.py`와 `.ts`도 있다. 파일을 보관할 수 있다는 사실과 서버가 그 언어를 실행한다는 사실은 다르다. [출처](https://neocities.org/site_files/allowed_types)

#웹사이트 #네오시티 #HTML #웹호스팅 #정적웹 #실천