문제 해결
더 많은 작업
흔한 문제와 확인할 점입니다.
섬네일 품질이 낮아 보여요
단독 실행 바이너리는 내장 GD 라이브러리로 대체 동작하는데, 이는 품질이 낮은 섬네일을 만들고 지원하는 형식도 적습니다. 더 나은 출력을 얻으려면 빌드 호스트에 ImageMagick과 librsvg를 설치하거나, 이들을 번들로 포함한 Docker 이미지를 사용하세요. 이미지 참고.
검색 상자가 아무 반응이 없어요
검색은 클라이언트 사이드로, SifterSearch를 통해 Wikven에 내장되어 있으며 기본적으로 켜져 있습니다. 상자가 반응하지 않는다면, 검색이 꺼져 있거나(SifterSearchOutputDir가 비어 있음), 번들 경로가 사이트가 제공되는 위치와 맞지 않는 것입니다(하위 디렉터리 배포에서는 SifterSearchBundlePath를 설정하세요). 검색 참고.
사이트에서 문서가 하나 빠져 있어요
문서 가져오기에 하나라도 실패하면 빌드가 중단되며, 파일 이름과 함께 Failed to import N page(s)를 출력합니다. 흔한 원인은 이름이 유효한 제목으로 대응되지 않는 파일입니다. 그런 파일은 이름을 바꾸세요 (이름이 왕복 변환되지 않으면 빌드가 경고합니다). 빌드를 다시 실행하고 실패한 파일에 대한 로그를 읽어 보세요.
HTTPS로 가져오기가 실패해요
위키미디어 공용 이미지와 서드파티 확장 기능이나 스킨을 가져오려면 시스템의 CA 인증서가 필요합니다. 이것이 없는 최소 구성 호스트(단독 실행 바이너리에서 흔함)에서는 배포판의 CA 번들, 예를 들어 ca-certificates 패키지를 설치하세요. 로컬 콘텐츠와 이미지만 있는 사이트는 네트워크 접근이 필요 없습니다.
바이너리가 macOS나 Windows에서 실행되지 않아요
단독 실행 바이너리는 Linux 전용입니다(x86_64와 arm64). macOS나 Windows에서는 대신 Docker 이미지를 사용하세요. 설치 참고.
.wikven.yaml의 설정이 아무 일도 하지 않습니다
먼저 빌드 로그를 읽으십시오. 눈에 보이는 실수는 로그가 경고합니다. unknown config는 여기에 불러온 것 중 어느 것도 정의하지 않는 이름이라는 뜻이고, 대개 오타입니다. 임자가 없는 이름도 그냥 적용된 뒤 무시되기 때문입니다. 경고는 알고 있는 설정 가운데 가장 가까운 이름을 함께 알려줍니다. 이 검사는 사이트가 나열한 확장 기능과 스킨이 모두 설치된 뒤에야 이루어집니다. 설정이 그중 어느 것에 속할 수도 있기 때문입니다. unknown top-level key는 config, extensions, skins 바깥에 있는 설정을 뜻합니다. URL 템플릿 경고는 WikvenEditUrl과 그 짝들에 $1이 빠졌다는 뜻입니다.
로그에 나오지 않아 직접 확인해야 하는 것이 하나 있습니다. config 값은 기본값과 합쳐지지 않고 대체하므로, 목록이나 맵을 설정할 때는 그대로 두고 싶었던 항목까지 모두 적어야 합니다. 설정을 참고하십시오.
확장 기능이나 스킨이 불러와지지 않았습니다
nothing provides extension 'X'는, 스킨이라면 같은 형태의 메시지는, extensions나 skins 목록의 이름을 디스크에서 찾지 못해 그것 없는 사이트를 발행하는 대신 빌드를 멈췄다는 뜻입니다. 철자가 틀렸거나, Wikven이 함께 제공하는 구성 요소가 아니어서 WikvenRepositories 맵에 소스가 필요한 경우입니다. 확장 기능을 참고하십시오.
설정 파일이 둘인데 하나가 무시됩니다
multiple site config files present는 소스 디렉터리에 받아들여지는 이름의 파일이 둘 이상 있다는 뜻입니다. 우선순위가 앞선 것이 쓰이고 나머지는 무시되므로, 빌드가 읽지도 않는 파일을 고치는 대신 원하지 않는 쪽을 지우십시오.
모든 문서가 같은 날 편집된 것으로 나옵니다
문서 날짜는 각 소스 파일을 마지막으로 바꾼 커밋에서 오는데, 얕은 클론에는 커밋이 하나뿐입니다. 온전한 클론에서 빌드하십시오. --depth 없이 클론하거나, 이미 있는 얕은 클론이라면 git fetch --unshallow로 채우면 됩니다. GitHub Actions에서는 배포하기의 워크플로처럼 fetch-depth: 0이 그것입니다. 저장소가 아닌 디렉터리에서 빌드해도 마찬가지이며, 두 경우 모두 빌드가 실패하지는 않습니다. 로그가 그렇게 되었다고 적고, 모든 문서는 빌드 중인 커밋으로 날짜가 찍힙니다.
위키미디어 공용 이미지에서 빌드가 실패합니다
공용 이미지를 담은 문서를 파싱할 때마다 공용에 섬네일을 묻습니다. Wikven은 실패한 조회를 두 번 더 시도한 뒤 포기하며, 그때는 구멍 난 문서를 내보내는 대신 해결하지 못한 이미지의 이름을 밝히고 멈춥니다. 파일 이름이 맞는지, 공용에 아직 있는지, 그리고 빌드 호스트가 네트워크에 닿는지 확인하십시오. 위의 HTTPS로 가져오기가 실패합니다도 함께 보십시오.
어떤 스킨의 렌더링이 실패했습니다
스킨이 여럿인 사이트에서는 각 스킨을 별도 프로세스가 렌더링하며, 빌드는 실패한 스킨을 이름과 함께 보고합니다(build failed for skin ...). 각 렌더링의 출력은 자기 제목 아래에 묶여 출력되므로, 로그의 끝이 아니라 그 스킨의 구간을 읽으십시오. 기계의 메모리가 부족하다면 WIKVEN_BUILD_JOBS=1로 렌더링을 하나씩 실행할 수 있습니다. 명령어를 참고하십시오.