설정
더 많은 작업
설정은 소스 디렉터리의 .wikven.yaml 파일에 담깁니다. 이 파일은 MediaWiki 자체의 YAML 설정 형식과 같은 구조를 따릅니다. 최상위 extensions 목록, skins 목록, 그리고 config 맵으로 이루어집니다.
파일 이름은 유연합니다. Wikven은 .wikven.yaml, .wikven.yml, .wikven.json과 앞에 점이 없는 같은 세 가지(wikven.yaml, wikven.yml, wikven.json)를 받아들이며, .json 형식은 YAML이 JSON의 상위 집합이므로 같은 구조를 씁니다. 여러 개가 있으면 그 순서대로 첫 번째가 우선하고 나머지는 경고와 함께 무시되므로, 점이 붙은 이름이 평범한 이름보다 우선하고, YAML이 JSON보다, .yaml이 .yml보다 우선합니다.
Wikven은 자체 기본값(정적 위키를 위한 합리적인 MediaWiki 설정)을 제공하며 그 위에 여러분의 파일을 얹어 읽으므로, 여기서 설정한 것은 무엇이든 기본값을 덮어씁니다. 기본값은 이와 같은 형식을 쓰는 default.yml에 들어 있습니다. 아래 기본값을 참고하십시오.
extensions:
- SyntaxHighlight_GeSHi
- ParserFunctions
skins:
- MinervaNeue
config:
Sitename: Wikven
WikvenEditUrl: https://github.com/yourname/some-repository/edit/branch-name/path/to/$1
WikvenHistoryUrl: https://github.com/yourname/some-repository/commits/branch-name/path/to/$1
extensions
불러올 확장 기능 이름의 목록입니다. Wikven 안에 함께 들어 있는 확장 기능은 이름만으로 작동하며, 그 밖의 이름은 서드파티로 취급되어 WikvenRepositories 맵에 선언한 소스에서 가져옵니다. 무엇이 들어 있고 무엇이 들어 있지 않은지는 확장 기능을 참고하십시오.
skins
활성화할 스킨 이름의 목록입니다. WikvenBuildVector를 끄지 않는 한, 무엇을 나열하든 Vector는 빌드됩니다. 단, 2.0부터는 이 목록이 Vector를 대체합니다. 어느 스킨으로 사이트를 읽을지는 config 아래 DefaultSkin으로 정하며, 설정하지 않으면 빌드된 첫 스킨입니다. 확장 기능과 마찬가지로 번들되지 않은 이름은 WikvenRepositories 맵에서 가져옵니다. 스킨을 참고하십시오.
config
각각 wg 접두사 없이 이름을 붙인 설정 변수의 맵으로, MediaWiki의 YAML 설정 형식과 똑같습니다. 어떤 설정 값이든 여기에 정의할 수 있고, 여러분이 불러오는 확장 기능이나 스킨이 스스로 선언한 설정도, Wikven 자체 변수도 정의할 수 있는데, 아래 절들이 그것을 하나씩 설명합니다.
여기에 나오지 않는 일곱 가지가 더 있지만 여러분이 설정할 것은 아닙니다. WikvenSourceDirectory, WikvenHtmlDirectory, WikvenSourceHistoryFile은 빌드가 WIKVEN_WORKDIR에서 직접 이끌어냅니다(명령어 참고). WikvenSkins, WikvenMainSkin, WikvenMissing, WikvenRefused는 위의 목록에서 빌드가 계산해 냅니다. 각각 사이트가 어떤 스킨으로 빌드되는지, 그중 어느 것으로 읽히는지, 사이트가 요청한 것 중 여기 없는 것이 무엇인지, 그리고 사이트가 요청한 것 중 빌드가 하지 않을 것이 무엇인지입니다. 어느 것이든 여러분의 파일에서 설정해도 쓸모가 없으며, 어차피 빌드가 덮어씁니다.
WikvenLogos
기본값: 비어 있음
사이트의 헤더 로고입니다. MediaWiki의 $wgLogos를 본떠 같은 키(icon, 1x, svg, wordmark 등)를 쓰지만, 각 값이 URL이 아니라 소스 디렉터리에 있는 이미지 파일의 이름이라는 점만 다릅니다:
config:
WikvenLogos:
icon: logo.svg
파일의 주소는 여러분이 아니라 빌드가 정하기 때문에 값이 URL이 아니라 파일 이름입니다. 이름이 지정된 각 파일은 다른 소스 이미지와 마찬가지로 File: 이름공간에 업로드되고, Wikven이 여러분을 대신해 $wgLogos를 그 업로드로 가리키므로 여러분은 파일 이름만 대면 됩니다. 그런 다음 내보내기는 다른 이미지와 똑같이 로고를 자산 디렉터리의 단일 공유 파일로 복사하고 그것을 가리키도록 레퍼런스를 다시 씁니다. 그래서 로고가 모든 문서에 삽입되지는 않습니다. 아무 파일도 대지 않으면 MediaWiki 자체가 보여 주는 로고가 그대로 쓰입니다.
Wikven은 또한 브라우저가 /favicon.ico에서 404를 내지 않도록 작은 기본 파비콘도 함께 제공합니다. config.Favicon(URL이나 데이터 URI)으로 이를 재정의하십시오.
WikvenEditUrl, WikvenHistoryUrl 및 WikvenViewSourceUrl
기본값: 비어 있음
"편집", "역사 보기", "원본 보기" 링크가 가리키는 대상으로, 독자가 렌더링된 문서에서 리포지터리의 소스로 건너뛸 수 있게 합니다. 각 URL에서 $1은 확장자를 포함해 소스 디렉터리를 기준으로 한 문서 소스 파일 이름으로 치환됩니다. 제목이 자체 콘텐츠 모델을 지니는 문서는 확장자를 그대로 유지하고(MediaWiki/Common.css, MediaWiki/Common.js, .json 설정 문서, Module/의 문서 등), 그 밖의 모든 문서는 .wikitext 파일이므로 평범한 문서는 Getting Started.wikitext가 됩니다. 이들 중 어느 것이든 설정하지 않으면 해당 링크가 빠집니다. 생성된 문서(빌드가 직접 쓴 라이선스 문서 같은)에는 소스 파일이 없으므로 이 링크들은 생략됩니다.
WikvenMainPage
기본값: index
정적 호스트가 사이트 최상단에서 제공할 문서의 제목입니다. 모든 문서는 자기 제목 뒤에 .html을 붙인 이름으로 작성되므로, 제목이 index여야 하는 것은 이 문서뿐입니다. 진입 파일 이름을 index.wikitext로 지으면 별도 설정이 전혀 필요 없습니다. 다른 이름의 문서를 지정하면 <그 제목>.html로 작성되고, 호스트가 제공할 index.html이 사이트에 없게 됩니다. 이 문서는 여러분이 가져온 문서여야 하며, 없으면 빌드가 실패합니다.
WikvenLicensesPage
기본값: Licenses
사이트가 게시하는 것 가운데 사이트 자신의 것이 아닌 것과 그 라이선스를 밝히는 문서의 제목으로, 모든 문서의 바닥글이 이 문서를 링크합니다. 빌드된 사이트는 여러분의 글과 함께 MediaWiki 자체의 스크립트와 각 스킨·확장 기능의 스타일을 게시하므로 그것들을 밝히는 무언가가 있어야 하는데, 아무 데서도 링크하지 않는 문서는 그 역할을 하지 못합니다. 빌드는 자신이 돌아간 환경 — MediaWiki와 PHP, 데이터베이스 — 을 먼저 적고, 이어서 여러분의 확장 기능과 스킨을 각각이 스스로 밝힌 버전 및 라이선스와 함께 적습니다. 앞의 셋 가운데 라이선스를 적는 것은 MediaWiki 하나인데, 그 스크립트만이 사이트와 함께 나가기 때문입니다. PHP와 데이터베이스는 그렇지 않으므로, 그 옆에 라이선스를 적으면 여러분의 사이트가 그것들을 실어 보낸다는 주장으로 읽힙니다. 번역이 있는 사이트에서는 언어마다 한 번씩 Licenses/<언어>에 쓰이므로, 바닥글 링크는 독자가 읽을 수 있는 사본으로 이어집니다. 대상 언어는 여러분의 문서에 번역이 있는 언어들입니다. 같은 이름의 소스 문서를 쓰면 그 내용이 대신 그대로 쓰이며, 그 아래 언어별 사본도 빌드가 쓰지 않습니다. 비워 두면 문서를 아예 쓰지 않으며, 바닥글 링크도 함께 사라집니다.
MediaWiki 자체의 "소개" 바닥글 링크는 별개이며, 빌드가 채워 주지 않습니다. MediaWiki:Aboutpage가 가리키는 문서가 없으면 그 항목은 다른 죽은 링크들과 함께 비워집니다. 그 링크를 두고 싶은 사이트는 소개 문서를 직접 쓰고, 그 문서를 가리키는 MediaWiki/Aboutpage.wikitext를 함께 두면 됩니다.
WikvenFooterBadge
기본값: true
모든 문서의 바닥글에 wikven 배지를 넣을지 여부입니다. MediaWiki 자체 배지와 같은 모양으로 그려져 그 옆에 놓입니다. false로 두면 빌드가 배지를 쓰지 않습니다. 여러분 자신의 글과 함께 사이트가 게시하는 것은 그래도 라이선스 문서에 밝혀지며, 그 문서는 모든 문서의 바닥글이 링크합니다. 그 MediaWiki 배지는 wikven이 아니라 MediaWiki의 것이므로 어느 쪽으로 두든 남고, 여러분이 직접 쓴 FooterIcons도 이 값을 어느 쪽으로 두든 그대로 둡니다.
WikvenFooterUrl
기본값: 비어 있음
여러분의 프로젝트(보통 그 리포지터리)를 가리키며 사이트 바닥글에 추가되는 링크입니다. 바닥글은 알려진 포지(GitHub, GitLab, Codeberg 등)의 경우 호스트 이름을 표시합니다. URL이 없으면 그런 링크도 없습니다.
WikvenSiteUrl
기본값: 비어 있음
이 사이트가 게시될 주소이며, 경로까지 포함해 슬래시로 끝냅니다 — https://example.org/wiki/. 빌드는 이것을 스스로 알아낼 수 없습니다. 설치는 로컬 서버를 상대로 하고, 페이지 링크는 전부 자기 옆의 파일로 적는데, 그 덕분에 내보낸 결과물이 어느 디렉터리에서도 어느 호스트에서도 열립니다. 사이트 바깥에서 페이지를 가리켜야 하는 것들은 이 값에서 만들어집니다. 주소를 적어두면 빌드가 내보낸 페이지를 모두 담은 sitemap.xml을 씁니다. 비어 있으면 — 기본값입니다 — 사이트맵을 쓰지 않습니다. 독자가 따라갈 수 없는 URL은 없느니만 못하기 때문입니다. 어느 쪽이든 페이지 자체는 달라지지 않습니다. 링크는 그대로 상대 경로이고 결과물은 여전히 어디로든 옮길 수 있습니다. 스킴과 호스트는 $wgCanonicalServer도 채우므로, MediaWiki나 확장기능이 만드는 절대 URL이 올바른 호스트를 가리킵니다. http나 https URL이 아닌 값은 보고되고 비어 있는 것으로 읽힙니다.
WikvenSettingsPage
기본값: Settings
빌드가 독자 자신의 표시 선택을 위해 쓰는 문서의 제목입니다. 색 테마, 그리고 스킨을 둘 이상으로 빌드한 사이트에서는 어떤 스킨으로 읽을지가 여기에 담깁니다. 이 선택은 독자의 브라우저에 보관되며 해당 사이트에만 적용되고, 계정은 관여하지 않습니다. 살아 있는 위키라면 제공했을 환경 설정을 대신하는데, 정적 내보내기에는 그럴 서버가 없기 때문입니다.
그 이름의 소스 문서를 쓰면 라이선스 문서와 똑같이 그쪽이 우선합니다. 빈 값으로 두면 문서를 아예 쓰지 않으며, 그곳을 가리키던 항목들도 함께 사라집니다. 이 문서가 독자에게 무엇을 제공하는지는 스킨을 참고하십시오.
WikvenBundleWebfonts
기본값: false
이 값을 설정하고 UniversalLanguageSelector를 켜면, 빌드가 문서에서 쓰는 언어들의 웹폰트를 내보내기가 스스로 제공하는 스타일시트로 구워 넣습니다. 어떤 문자의 글꼴이 시스템에 없는 독자도 빈 네모 대신 의도한 글꼴을 보게 됩니다. 따로 요청하지 않으면 꺼져 있는데, 글꼴은 그것이 필요하지 않을 수도 있는 독자에게까지 추가로 전송되는 용량이기 때문입니다. UniversalLanguageSelector가 없으면 아무 일도 하지 않습니다. 번역하기를 참고하십시오.
WikvenFailOnCategories
기본값: 미디어위키와 번들 확장 기능이 이미 추적하고 있는 결함들
빌드가 끝났을 때 어떤 문서도 들어 있어서는 안 되는 분류들입니다. 그중 하나에 문서를 넣은 빌드는 멈추고, 어느 문서가 들어갔는지 말합니다.
미디어위키는 제대로 렌더링하지 못하는 문서를 거절하지 않습니다. 할 수 있는 만큼 렌더링하고 그 문서를 추적 분류에 넣습니다. 필수 인자 없이 쓰인 틀은 자리표시자를 그리고, Lua 오류는 모듈의 답이 있어야 할 자리에 인쇄되며, 각주는 문서가 대지 않은 출처를 가리키고, 틀 전개가 한도를 넘은 문서는 잘린 채로 끝납니다. 하나같이 빌드되고, 게시되고, 아무도 쓰지 않은 무언가로 읽힙니다. 그렇다고 말해 주는 것은 분류뿐인데, 정적 내보내기는 분류를 담지 않습니다.
기본값은 미디어위키와 번들 확장 기능이 이미 추적하고 있는 그 결함들 전부입니다. 따라서 아무것도 설정하지 않은 사이트도 이미 그것들에서 멈춥니다. 빠져 있는 것은 결함이 아니라 선택을 기록하는 분류들입니다. 숨은 분류, 색인된 문서와 색인되지 않은 문서, 매직 링크, 그리고 낡은 문법이 얼마나 남았는지 세는 분류들인데, 어느 것도 빌드를 거절할 이유가 되지 않습니다.
한 항목은 추적 분류의 메시지 키로 적습니다. 미디어위키가 이 분류들의 이름을 그렇게 두기 때문입니다. 미디어위키 어디에도 "Pages with template loops"라고 적혀 있지 않고 template-loop-category라고 적혀 있으며, 다른 언어로 읽는 위키는 그 키에 자기 이름으로 답합니다. 사이트가 불러오지 않은 확장 기능의 키는 아무것도 가리키지 않으므로 그냥 넘어갑니다. 기본값 중 하나를 빼려면 그 메시지를 -로 고치십시오. 추적 분류를 끄는 미디어위키 자신의 방식입니다.
메시지 키가 아닌 것은 분류 이름으로 읽으며, Category: 접두어는 붙여도 되고 붙이지 않아도 됩니다. 사이트가 적은 것은 기본값을 대체하지 않고 기본값에 더해집니다. 틀이 스스로 문서를 분류에 넣을 수 있습니다.
{{#if:{{{1|}}}||[[Category:Pages with template errors]]}}
분류에는 __HIDDENCAT__를 넣어 문서 하단에 나오지 않게 하십시오. 내보내기에는 분류 문서가 들어가지 않으므로, 없는 문서로 가는 링크가 됩니다.
WikvenFileNames
기본값: readable
문서가 출력에서 어떤 이름으로 놓이는지, 따라서 그 문서를 가리키는 모든 링크가 무엇이라고 쓰는지를 정합니다. 기본값은 제목을 쓴 그대로 이름 짓습니다. Vector_(skin).html, File:Bakery_oven.jpg.html 같은 식이고, 가장 깔끔한 URL이 되며 이 문서 사이트도 이 값으로 게시됩니다. 링크가 지니는 것은 그 이름을 URL 인코딩한 것입니다. 정적 서버는 요청받은 경로를 디코드한 뒤에 파일을 찾기 때문입니다.
출력 디렉터리가 윈도우 파일 시스템이라면 encoded로 설정하십시오. 윈도우는 이름에 콜론이 든 파일을 담지 못하므로, Docker Desktop의 바인드 마운트는 기본값으로는 주 이름공간 밖의 문서를 받을 수 없습니다. encoded는 문서 캐시가 만든 이스케이프를 그대로 둡니다. File%3ABakery_oven.jpg.html처럼 되고, 어떤 파일 시스템이든 담을 수 있습니다. 대가는 URL에 그 퍼센트가 한 번 더 붙는 것입니다. 그 문서로 가는 링크는 ./File%253ABakery_oven.jpg.html이 됩니다. 링크는 이름을 URL 인코딩한 것이고, 그 이름 자체에 퍼센트가 들어 있기 때문입니다.
윈도우가 담지 못하는 문자가 넷 더 있습니다. 큰따옴표, 별표, 물음표, 역슬래시입니다. 이들은 두 값 모두에서 이스케이프된 채로 남으므로, What?이라는 문서는 어느 쪽에서도 What%3F.html로 놓입니다. 제목에 드물게 쓰이는 문자이고 이스케이프된 채로 두어도 읽기에 잃는 것이 없으니, 그런 문자를 쓸 일이 없는 사이트는 encoded가 아예 필요하지 않게 됩니다.
이 값을 바꾸면 사이트가 제공하는 모든 URL이 바뀝니다. 다른 사람이 어떤 문서로 걸어 둔 링크는 예전 이름을 계속 가리키는데, 그 이름은 이제 없습니다. 게시한 뒤가 아니라 게시하기 전에 정하십시오.
WikvenBuildFor
기본값: site
skin-preview로 두면 본문을 감싼 것들을 건드리지 않습니다. 개인 메뉴도, 도구모음도, 탭도, 푸터도 Wikven이 해석한 모습이 아니라 스킨이 그린 그대로이며, 몇 쪽을 구워 자기 스킨을 보려는 사람이 보고 싶은 것이 그것입니다. 출력을 동작하는 파일 묶음으로 만드는 일은 전부 그대로 합니다.
이 모드는 실험적이며, 앞으로도 그렇습니다. 스킨은 여러 MediaWiki 판을 상대로 작성되지만, 굽기는 Wikven이 싣고 있는 한 판에서만 렌더됩니다. 그래서 얻는 것은 그 판에서의 내 스킨이고 다른 판에 대해서는 아무 근거도 되지 않습니다. 스킨 저자에게는 모자라고, 이 프로젝트가 넓힐 수 있는 범위는 넘습니다. Wikven 저장소의 examples/skin-preview가 이 모드로 구울 원본 트리이며, 설명은 그 README에 있습니다.
WikvenBuildVector
기본값: true
false로 설정하면 Vector 없이 빌드합니다. 설정하지 않으면 기본값이 모든 사이트의 skins에 Vector를 더합니다. 사이트가 Vector를 직접 나열했거나 다른 스킨을 하나도 나열하지 않았다면 Vector는 그대로 빌드됩니다. 사이트에는 스킨이 하나는 있어야 하기 때문입니다. 이 설정은 임시방편입니다. 2.0에서는 사이트의 skins 목록이 기본값을 대체하므로, 원하는 스킨을 나열하는 것이 Vector를 빼는 방법이 되고 이 설정은 지원 중단됩니다. 스킨을 참고하십시오.
WikvenAssetDirectory
기본값: assets
빌드가 만들어 내는 것을 출력 디렉터리 아래 어디에 쓸지입니다. MediaWiki에서 뽑아낸 스타일시트와 스크립트 번들, 그리고 그 CSS가 이름을 부르는 이미지와 웹폰트 파일이 모두 여기에 들어갑니다. 경로는 출력 디렉터리 기준이고 빌드가 링크도 거기에 맞춰 쓰므로, 따로 알려 줄 것은 없습니다.
스타일시트는 자기 위치를 기준으로 한 상대 경로로 이미지를 부르기 때문에 둘을 떼어 놓을 수 없습니다. 그래서 종류별로 나누지 않고 한 디렉터리입니다. .로 두면 전부 출력 루트에 문서들과 함께 놓입니다.
config:
WikvenAssetDirectory: .
WikvenRepositories
기본값: 비어 있음
extensions와 skins에 나열한 서드파티 확장 기능과 스킨의 소스입니다. 목록은 평범한 이름 그대로 유지되고(MediaWiki 자체가 쓰는 형태), 이 맵은 wikven에 번들되지 않은 것들을 어디서 가져올지 지정합니다. 이들은 MediaWiki가 불러오기 전에 빌드 시점에 가져옵니다. 항목이 확장 기능인지 스킨인지는 그 이름이 어느 목록에 나타나는지에 따라 정해지므로 이름을 두 번 쓸 일이 없습니다. extensions나 skins에 적힌 이름이 번들되지도, 여기에 선언되지도 않았다면 빌드가 실패합니다. 작성자가 요청한 것 없이 발행된 사이트가 아예 빌드되지 않은 사이트보다 나쁘기 때문입니다.
각 항목은 지닌 키에 따라 세 가지 방법 중 하나를 고릅니다:
config:
WikvenRepositories:
# 1. 타르볼. 예를 들어 Special:ExtensionDistributor에서 받은, 확장 기능의 의존성이
# 이미 아카이브에 들어 있는 것. 내려받은 파일을 검증하려면 sha256을 추가하십시오.
Foo:
tarball: https://extdist.wmflabs.org/dist/extensions/Foo-REL1_46-abc1234.tar.gz
sha256: 4f5e... # 16진수 64자. 일치하지 않으면 빌드가 중단됩니다
# 2. Git 리포지터리. commit(정확한 SHA, 재현 가능)이나 reference(태그나 브랜치)로
# 고정하십시오. 복제된 디렉터리 안에서 Composer를 실행하려면
# composer: true를 추가하십시오.
Bar:
repository: https://github.com/example/Bar.git
commit: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
composer: true
# 3. Composer 패키지. MediaWiki의 composer.local.json을 통해 해결됩니다.
SemanticMediaWiki:
package: mediawiki/semantic-media-wiki:~4.1
이미 wikven에 번들된 WikvenRepositories 속 이름은 건드리지 않습니다. extensions나 skins에도 나열되지 않은 이름은 오류입니다.
package에서는 그 이름을 여러분이 아니라 Composer가 정합니다. mediawiki-extension 패키지는 뒤에 붙은 -extension을 떼고 CamelCase로 바꾼 디렉터리에 설치되고(mediawiki/tabber-neue-extension은 extensions/TabberNeue가 됩니다), mediawiki-skin 패키지는 CamelCase로 바뀌지 않습니다(mediawiki/chameleon-skin은 skins/chameleon이 됩니다). 빌드가 불러오는 것은 그 디렉터리이므로, 나열하는 이름도 그것이어야 합니다. 설치가 끝난 뒤에 검사해서 맞지 않으면 이름을 알려 주므로, 구성 요소 없이 사이트가 게시되는 대신 빌드가 멈춥니다.
정확한 버전이 아닌 package 제약 — ~4.1, ^4, * — 은 아래 알림이 말하는 이유로 빌드 로그에 경고가 남습니다. 오류는 아닙니다. 레지스트리가 주는 대로 받는 것은 여러분이 택할 수 있는 거래이고, 움직이는 reference가 하는 것과 같은 거래이며, 빌드는 그 거래를 했다는 사실만 말해 줄 뿐입니다.
각 방법은 빌드 시점에 존재하는 호스트 도구가 필요합니다. tarball은 tar를, repository는 git을(그리고 composer: true일 때 Composer를), package는 Composer를 씁니다. Docker 이미지는 이 모두를 번들하지만, 단독 실행 바이너리에서는 이들이 PATH에 있어야 합니다.
여기서 이름을 대는 코드를 빌드가 네트워크 접근과 함께 내려받아 실행합니다. 복제된 확장 기능의 PHP와 모든 Composer 스크립트가 빌드 중에 실행됩니다. 신뢰하는 소스만 선언하십시오. 변조를 알아챌 수 있고 재현 가능한 빌드를 위해서는 타르볼을 sha256으로, 리포지터리를 commit(정확한 SHA)으로 고정하십시오. 가변적인 reference 태그/브랜치나 유동적인 package 제약은 여러분 모르게 바뀔 수 있습니다.
다만 정확한 핀을 여러분 대신 옮겨 주는 것은 없습니다. 이 파일은 의존성 봇이 읽는 어떤 생태계에도 속하지 않으므로, 그대로 둔 핀은 뒤처진 핀이 됩니다. 핀을 최신으로 유지하는 방법은 배포하기를 참고하십시오.
wikven을 옮기면 이 핀들 밑에 깔린 코어도 함께 옮겨집니다. wikven의 메이저 버전은 번들된 MediaWiki가 올라갈 때마다 함께 올라가고, 그것은 대략 1년에 두 번입니다. WikvenRepositories를 선언한 사이트는 wikven이 시험하지 않는 코드를, wikven의 것이 아닌 릴리스 일정 위에서 안고 있는 셈입니다. 메이저를 건너간다는 것은 그 코드에 한 번도 돌아 본 적 없는 MediaWiki를 쥐여 주는 일입니다.
그때 일어날 수 있는 일은 두 가지이고, 그중 붙잡히는 것은 하나뿐입니다. 새 코어를 배제하는 코어 범위를 선언한 구성 요소는 빌드를 멈춰 세웁니다. MediaWiki의 VersionChecker가 incompatible-core를 일으키면서 그 구성 요소와 그것이 요구한 범위를 알려 줍니다. 하한만 선언해 놓고 그래도 깨지는 구성 요소는 아무것도 알아채지 못합니다. 그리고 두 번째가 예외가 아니라 보통의 경우입니다. 이 사이트가 고정해 둔 Citizen v3.21.0과 TabberNeue v4.0.2는 둘 다 MediaWiki: >= 1.43.0을 요구할 뿐 그 위로는 아무 말도 하지 않습니다. 그것이 그들이 정직하게 할 수 있는 선언입니다. 요구 사항은 릴리스 시점에 쓰이는데 배제해야 할 코어는 그때 아직 존재하지 않고, 나중에 누군가 그 비호환을 발견하더라도 생태계에는 그것을 적어 둘 자리가 없습니다. 아무도 적어 둘 수 없는 것을 검사로 만들 수는 없습니다.
그러니 wikven을 메이저 너머로 옮길 때는 고정해 둔 구성 요소를 여러분이 직접 다시 확인하십시오. 사이트를 빌드해서 그것들이 렌더링한 문서를 읽어 보는 것입니다. 빌드가 초록색이라는 것은 핀이 해결되었고 그것들이 선언한 범위가 충족되었다는 말이지, 여전히 동작한다는 증거는 아닙니다.
바로 이 사이트도 이 방식으로 TabberNeue를 가져옵니다(그 .wikven.yaml 참고). 시작하기에 있는 탭 형식의 Docker/바이너리 명령 예시는 가져온 이 확장 기능이 렌더링한 것입니다. (이 사이트의 틀이 쓰는 TemplateStyles는 MediaWiki에 번들되어 있어 여기에 소스가 필요 없습니다.)
ContentNamespaces
기본값: [0, 6]
어떤 문서를 wikven이 내보낼지 정하는 표준 MediaWiki 설정($wgContentNamespaces)입니다. 콘텐츠 이름공간에 있는 문서만 정적 사이트로 작성됩니다. Wikven은 주 이름공간과 File: 이름공간을 지정하므로, 모든 Template:이나 MediaWiki: 문서를 쏟아내지 않고도 파일 설명 문서가 내보내집니다. 분류 문서도 내보내려면 분류 이름공간(14)을 추가하십시오. 문서의 분류 섹션을 참고하십시오. config 값은 기본값을 확장하는 것이 아니라 대체하므로, 유지하려는 기본값을 포함해 원하는 전체 집합을 나열하십시오.
RawHtml
기본값: false
이것도 표준 MediaWiki 설정($wgRawHtml)으로, wikven은 꺼 두지만 사이트가 켤 수 있습니다. true로 두면 문서가 <html> 태그 안에 자기 HTML을 담을 수 있고, 빌드는 그것을 받은 그대로 문서에 써 넣습니다. 위키텍스트가 허용하지 않는 요소와 속성, <script>와 이벤트 핸들러까지 포함해서입니다.
config:
RawHtml: true
<html><iframe src="https://example.org/embed" width="560" height="315"></iframe></html>
살아 있는 위키가 이것을 꺼 두는 까닭은, 문서를 편집할 수 있는 누구나 모든 독자의 브라우저에서 스크립트를 돌릴 수 있게 되기 때문입니다. Wikven 사이트에는 소스 디렉터리를 바꿀 수 있는 사람 말고는 편집자가 없고, 그들은 이미 MediaWiki:Common.js를 바꿀 수 있으므로, 이것을 켠다고 누구에게 없던 권한이 생기지는 않습니다. 대신 그 HTML이 담은 것은 전부 여러분의 몫이 됩니다. 아무것도 그것을 검사하지 않고, 그것은 바뀌지 않은 채 독자에게 닿습니다.
바뀌지 않는다는 것은 다시 쓰이지도 않는다는 뜻입니다. 위키텍스트의 링크는 그것이 빌드되는 파일의 상대 경로가 되지만, <html> 안의 링크는 쓴 그대로 남습니다. 그러니 빌드된 파일의 이름(밑줄이 들어간 Getting_Started.html)을 쓰고, 하위 문서에서라면 거기까지 거슬러 올라가는 경로도 함께 쓰십시오. 이 태그는 문서와 문서가 쓰는 틀에서는 동작하지만 인터페이스 메시지에서는 동작하지 않습니다. MediaWiki:Sitenotice처럼 스킨이 그리는 MediaWiki: 문서에는 그 자리에 오류가 대신 표시됩니다.
기본값
여러분의 .wikven.yaml을 읽기 전에 Wikven은 wikven에 번들된 default.yml의 자체 기본값을 적용합니다. 이는 여러분의 설정과 같은 형식으로 작성되어 있어, Wikven이 여러분을 위해 무엇을 설정하는지 알려 주는 레퍼런스 역할도 겸합니다. 사이트 이름, 그대로 유지되는 문서 제목, InstantCommons, (SVG를 포함한) 로컬 이미지 업로드, Vector 2022 스킨 옵션 등입니다. 또한 extensions와 skins 기본값도 제공하므로, 모든 사이트가 따로 나열하지 않아도 SifterSearch 검색과 Vector 스킨을 얻습니다. 여러분의 .wikven.yaml이 그 위에 병합되어, 여러분의 config 키가 기본값을 덮어쓰고 여러분의 extensions와 skins가 뒤에 덧붙습니다.
제목은 (MediaWiki 기본값인 첫 글자 대문자화가 아니라) 작성된 그대로 유지되므로, 진입 문서를 소문자 index로 둘 수 있습니다. 빌드는 이를 index.html로 작성하며, 이는 정적 호스트가 사이트 루트에서 제공하는 파일입니다. 그 밖의 파일에는 주석이 달려 있으며, 각 주석은 Wikven이 그 값을 설정하는 이유를 적어 둡니다.
현재 기본값을 보려면 번들된 default.yml을 읽으십시오. Docker 이미지에서:
docker run --rm --entrypoint cat ghcr.io/chaotic-ground/wikven extensions/Wikven/default.yml
이는 리포지터리에도 있습니다.