설정
더 많은 작업
설정은 소스 디렉터리의 .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
불러올 확장 기능 이름의 목록입니다. 번들된 확장 기능은 이름만으로 작동하며, 번들되지 않은 이름은 서드파티로 취급되어 WikvenRepositories에 선언한 소스에서 가져옵니다.
skins
활성화할 스킨 이름의 목록입니다. 첫 번째가 기본 스킨으로 쓰입니다. 확장 기능과 마찬가지로 번들되지 않은 이름은 WikvenRepositories에서 가져옵니다. 스킨을 참고하십시오.
config
각각 wg 접두사 없이 이름을 붙인 설정 변수의 맵으로, MediaWiki의 YAML 설정 형식과 똑같습니다. 어떤 설정 값이든 여기에 정의할 수 있으며, WikvenMainPage, WikvenEditUrl, WikvenHistoryUrl, WikvenViewSourceUrl, WikvenAboutPage, WikvenFooterUrl, WikvenLogos, WikvenRepositories 같은 Wikven 자체 변수도 포함합니다.
WikvenLogos
사이트의 헤더 로고입니다. MediaWiki의 $wgLogos를 본떠 같은 키(icon, 1x, svg, wordmark 등)를 쓰지만, 각 값이 URL이 아니라 소스 디렉터리에 있는 이미지 파일의 이름이라는 점만 다릅니다:
config:
WikvenLogos:
icon: logo.svg
파일의 주소는 여러분이 아니라 빌드가 정하기 때문에 값이 URL이 아니라 파일 이름입니다. 이름이 지정된 각 파일은 다른 소스 이미지와 마찬가지로 File: 이름공간에 업로드되고, Wikven이 여러분을 대신해 $wgLogos를 그 업로드로 가리키므로 여러분은 파일 이름만 대면 됩니다. 그런 다음 내보내기는 다른 이미지와 똑같이 로고를 HTML 옆의 단일 공유 파일로 복사하고 그것을 가리키도록 레퍼런스를 다시 씁니다. 그래서 로고가 모든 문서에 삽입되지는 않습니다.
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로 지으면 별도 설정 없이 작동합니다. 이 문서는 여러분이 가져온 문서여야 하며, 없으면 빌드가 실패합니다.
WikvenAboutPage
사이트를 소개하는 문서의 제목으로, MediaWiki 자체의 "소개" 바닥글 링크가 이 문서를 가리킵니다. 기본값은 About입니다. 같은 이름의 소스 문서를 쓰면 그 내용이 그대로 쓰이며, 빌드는 설치된 소프트웨어·확장 기능·스킨을 나열하는 Wikven software 틀(Special:Version이 보여 줄 내용으로, export에는 그런 특수문서가 없습니다)도 함께 생성하므로, 그 목록을 원하는 자리에 {{Wikven software}}로 넣거나 아예 빼면 됩니다. 같은 이름의 소스 문서가 없으면 빌드가 소개 문장과 그 아래 목록을 담은 문서를 씁니다. 비워 두면 문서를 아예 쓰지 않으며, 바닥글 링크도 함께 사라집니다.
WikvenFooterUrl
여러분의 프로젝트(보통 그 리포지터리)를 가리키며 사이트 바닥글에 추가되는 링크입니다. 바닥글은 알려진 포지(GitHub, GitLab, Codeberg 등)의 경우 호스트 이름을 표시합니다.
WikvenRepositories
extensions와 skins에 나열한 서드파티 확장 기능과 스킨의 소스입니다. 목록은 평범한 이름 그대로 유지되고(MediaWiki 자체가 쓰는 형태), 이 맵은 wikven에 번들되지 않은 것들을 어디서 가져올지 지정합니다. 이들은 MediaWiki가 불러오기 전에 빌드 시점에 가져옵니다. 항목이 확장 기능인지 스킨인지는 그 이름이 어느 목록에 나타나는지에 따라 정해지므로 이름을 두 번 쓸 일이 없습니다.
각 항목은 지닌 키에 따라 세 가지 방법 중 하나를 고릅니다:
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에도 나열되지 않은 이름은 오류입니다.
각 방법은 빌드 시점에 존재하는 호스트 도구가 필요합니다. tarball은 curl과 tar를, repository는 git을(그리고 composer: true일 때 Composer를), package는 Composer를 씁니다. Docker 이미지는 이 모두를 번들하지만, 단독 실행 바이너리에서는 이들이 PATH에 있어야 합니다.
여기서 이름을 대는 코드를 빌드가 네트워크 접근과 함께 내려받아 실행합니다. 복제된 확장 기능의 PHP와 모든 Composer 스크립트가 빌드 중에 실행됩니다. 신뢰하는 소스만 선언하십시오. 변조를 알아챌 수 있고 재현 가능한 빌드를 위해서는 타르볼을 sha256으로, 리포지터리를 commit(정확한 SHA)으로 고정하십시오. 가변적인 reference 태그/브랜치나 유동적인 package 제약은 여러분 모르게 바뀔 수 있습니다.
바로 이 사이트도 이 방식으로 TabberNeue를 가져옵니다(그 .wikven.yaml 참고). 시작하기에 있는 탭 형식의 Docker/바이너리 명령 예시는 가져온 이 확장 기능이 렌더링한 것입니다. (이 사이트의 틀이 쓰는 TemplateStyles는 MediaWiki에 번들되어 있어 여기에 소스가 필요 없습니다.)
ContentNamespaces
어떤 문서를 wikven이 내보낼지 정하는 표준 MediaWiki 설정($wgContentNamespaces)입니다. 콘텐츠 이름공간에 있는 문서만 정적 사이트로 작성됩니다. Wikven은 이를 [0, 6], 즉 주 이름공간과 File: 이름공간으로 기본 설정하므로, 모든 Template:이나 MediaWiki: 문서를 쏟아내지 않고도 파일 설명 문서가 내보내집니다. 분류 문서도 내보내려면 분류 이름공간(14)을 추가하십시오. 문서의 분류 섹션을 참고하십시오. config 값은 기본값을 확장하는 것이 아니라 대체하므로, 유지하려는 기본값을 포함해 원하는 전체 집합을 나열하십시오.
기본값
여러분의 .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
이는 리포지터리에도 있습니다.