Merge pull request 'Document how a repository opts in to wiki publishing' (#63) from mil-006-guides-and-wiki into main

Reviewed-on: #63

README.md

@@ -25,7 +25,7 @@ It currently contains the Gitea workflow [`sync-github-metadata.yml`](.gitea/sco
 - Repository secrets:
   - `TOKEN_FOR_GITEA`: Gitea API token (the token only, no JSON)
   - `PAT_FOR_GITHUB`: a GitHub personal access token allowed to edit the mirror repository (the token only, no JSON)
-  - `TOKEN_FOR_GITEA_WIKI` (optional, only in this repository, for the **Publish wiki** workflow): Gitea token that can write the repository wiki; when it is absent, `TOKEN_FOR_GITEA` is used and needs write access
+  - `TOKEN_FOR_GITEA_WIKI` (only for repositories that publish a wiki, see the [onboarding guide](guides/onboarding.md)): a Gitea token that can write the wiki, stored as a secret of the repository's organization; there is no fallback to `TOKEN_FOR_GITEA`
 
 ## 🛠️ Setup
 
@@ -59,13 +59,14 @@ After a change to the sync workflow, also trigger **Sync GitHub mirror metadata*
 
 ## 🟢 Capabilities
 
-Only the first row is implemented. The rest is planned and tracked in the [Project Plan](docs/project-plan.md), which also describes each use case.
+Rows that say Implemented or Guides written exist today. The rest is planned and tracked in the [Project Plan](docs/project-plan.md), which also describes each use case.
 
 | Capability | Status |
 | --- | --- |
 | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
 | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](guides/credentials.md)) |
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) |
+| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) |
 | Shared quality checks | Planned (MIL-003) |
 | Versioned release and publishing | Planned (MIL-004) |
 

guides/credentials.md

@@ -56,27 +56,29 @@ is ever printed.
 
 ## Wiki publishing secret
 
-The workflow **Publish wiki** (this repository only) copies `wiki/` to the Gitea
+The workflow **Publish wiki** copies `wiki/` to the Gitea wiki of a repository
-wiki when a change to `wiki/` is merged to `main`. It uses `TOKEN_FOR_GITEA_WIKI`
+that has opted in with `wiki/.publish` (see [onboarding.md](onboarding.md)). It
-when that secret exists and otherwise reuses `TOKEN_FOR_GITEA`.
+uses its own secret, so the metadata sync token stays read-only.
 
 | Secret | Content | Used for |
 | --- | --- | --- |
-| `TOKEN_FOR_GITEA_WIKI` (optional) | The Gitea token, nothing else | Writing the wiki pages of this repository |
+| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in |
 
-- The token that is used needs scope `write:repository`, and its user needs
+- Store it as a secret of the organization of each repository that publishes.
-  write access to this repository. Gitea has no wiki-only scope.
+  There is no fallback to `TOKEN_FOR_GITEA`: a repository that opted in and has
-- `TOKEN_FOR_GITEA` is documented above with `read:repository` only. Reusing it
+  no such secret fails with a configuration error, and a repository that did
-  for the wiki means raising its scope, which also gives the metadata sync
+  not opt in does not need it.
-  write access. A separate `TOKEN_FOR_GITEA_WIKI` for a dedicated user keeps
+- The token needs scope `write:repository`, and its user needs write access to
-  the sync token read-only. S05 decides which, and S03 stores the secret.
+  the repositories. Gitea has no wiki-only scope, so create the token for a
+  dedicated user. S05 approves the scope and S03 stores the secret.
 - Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`,
   `GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that
   no longer exists in `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
 - The wiki must be enabled in the repository settings. The workflow refuses to
   run when it is not.
-- The wiki always equals `wiki/`: pages edited or added in the Gitea web UI are
+- Pages that are in `wiki/` are always overwritten from it, so a change made
-  overwritten or removed on the next publish.
+  in the Gitea web UI is lost on the next publish. Pages that are only in the
+  wiki are removed only when `wiki/.publish` contains the word `prune`.
 
 ## Rotating a token
 

guides/onboarding.md

@@ -43,6 +43,27 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar
    and topics.
 7. If it fails, use [troubleshooting.md](troubleshooting.md).
 
+## Publish a wiki (optional)
+
+The **Publish wiki** workflow copies the Markdown pages in `wiki/` to the
+repository wiki when a change to `wiki/` is merged to `main`. It is delivered
+like the sync workflow, but it writes only where a repository opts in.
+
+1. Enable the wiki in the repository settings.
+2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is
+   the home page.
+3. Add the marker `wiki/.publish`. Leave it empty to create and update pages
+   only. Put the single word `prune` in it to also delete wiki pages that are
+   not in `wiki/`, so the wiki always equals the folder.
+4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
+   using the scope in [credentials.md](credentials.md).
+5. Merge the change to `main`. The log must end with `Published <n> page(s) to
+   the wiki of <owner>/<repo>`.
+
+A repository without `wiki/.publish` is skipped with the line `No
+wiki/.publish marker in <owner>/<repo>`: nothing is written and no secret is
+needed.
+
 ## Runners
 
 | Item | Value |

guides/troubleshooting.md

@@ -26,7 +26,8 @@ never starts, or stops before the step) is a **runner** problem.
 | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
 | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
-| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Wiki publishing only: add one of the secrets (see [credentials.md](credentials.md)) |
+| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository opted in with `wiki/.publish` but its organization has no such secret; store it (see [credentials.md](credentials.md)) |
+| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing only: leave the marker empty, or put only the word `prune` in it |
 | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
 | `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
 | `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: `wiki/` is empty or missing; nothing was changed |
@@ -51,6 +52,14 @@ settings.
 synced.` The run succeeds but nothing was synced. Check that the Gitea
 version supports the push mirror API and re-run.
 
+`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
+this repository.` The Publish wiki run succeeds and writes nothing. The
+repository has not opted in; add `wiki/.publish` if it should publish.
+
+`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word
+'prune' in wiki/.publish to delete them.` The run succeeds. Pages that exist
+only in the wiki are left alone unless the marker contains `prune`.
+
 ## Runner problems
 
 See the [Runners](onboarding.md#runners) section. In short: if the run stays

wiki/Capabilities.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 5856fdc70a30 -->
+<!-- translation of Capabilities.md, source sha256 737481cd7e09 -->
 
 > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -6,13 +6,14 @@
 
 ## Funktionalitet
 
-Kun den første række er implementeret. Resten er planlagt og følges i [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), som også beskriver hver enkelt use case.
+Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Resten er planlagt og følges i [projektplanen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), som også beskriver hver enkelt use case.
 
 | Funktionalitet | Status |
 | --- | --- |
 | Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow |
 | Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) |
 | Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til andre repositories er ikke verificeret endnu; korte use cases er åbne (MIL-002) |
+| Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; pilotforsøget i et andet repository afventer (MIL-006) |
 | Fælles kvalitetskontrol | Planlagt (MIL-003) |
 | Versioneret udgivelse og publicering | Planlagt (MIL-004) |
 

wiki/Capabilities.md

@@ -6,13 +6,14 @@ English | [Dansk](Capabilities.da) | [Bahasa Melayu](Capabilities.ms)
 
 ## Capabilities
 
-Only the first row is implemented. The rest is planned and tracked in the [Project Plan](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), which also describes each use case.
+Rows that say Implemented or Guides written exist today. The rest is planned and tracked in the [Project Plan](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), which also describes each use case.
 
 | Capability | Status |
 | --- | --- |
 | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
 | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) |
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to other repositories not yet verified; brief use cases open (MIL-002) |
+| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; the pilot in a second repository is pending (MIL-006) |
 | Shared quality checks | Planned (MIL-003) |
 | Versioned release and publishing | Planned (MIL-004) |
 

wiki/Capabilities.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 5856fdc70a30 -->
+<!-- translation of Capabilities.md, source sha256 737481cd7e09 -->
 
 > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -6,13 +6,14 @@
 
 ## Keupayaan
 
-Hanya baris pertama yang dilaksanakan. Selebihnya dirancang dan dijejaki dalam [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), yang juga menerangkan setiap kes guna (use case).
+Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Selebihnya dirancang dan dijejaki dalam [Pelan Projek](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/docs/project-plan.md), yang juga menerangkan setiap kes guna (use case).
 
 | Keupayaan | Status |
 | --- | --- |
 | Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan |
 | Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) |
 | Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori lain belum disahkan; use case ringkas masih terbuka (MIL-002) |
+| Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; juruterbang dalam repositori kedua belum dibuat (MIL-006) |
 | Semakan kualiti bersama | Dirancang (MIL-003) |
 | Keluaran dan penerbitan berversi | Dirancang (MIL-004) |
 

wiki/Credentials.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Credentials.md, source sha256 b810a21a07d5 -->
+<!-- translation of Credentials.md, source sha256 2660f2095b78 -->
 
 > Dette er en oversættelse af [`Credentials`](Credentials). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -48,17 +48,17 @@ Ved succes står der i loggen `Preflight passed: Gitea and GitHub accepted the c
 
 ## Secret til publicering af wiki
 
-Workflowet **Publish wiki** (kun dette repository) kopierer `wiki/` til Gitea-wikien, når en ændring af `wiki/` flettes til `main`. Det bruger `TOKEN_FOR_GITEA_WIKI`, hvis den secret findes, og genbruger ellers `TOKEN_FOR_GITEA`.
+Workflowet **Publish wiki** kopierer `wiki/` til Gitea-wikien i et repository, der har meldt sig til med `wiki/.publish` (se [onboarding.md](Onboarding.da)). Det bruger sin egen secret, så synkroniseringstokenet forbliver skrivebeskyttet.
 
 | Secret | Indhold | Bruges til |
 | --- | --- | --- |
-| `TOKEN_FOR_GITEA_WIKI` (valgfri) | Gitea-tokenet, intet andet | At skrive wikisiderne for dette repository |
+| `TOKEN_FOR_GITEA_WIKI` | Gitea-tokenet, intet andet | At skrive wikisiderne for de repositories i en organisation, der melder sig til |
 
-- Det token, der bruges, skal have scope `write:repository`, og dets bruger skal have skriveadgang til dette repository. Gitea har intet scope kun til wikien.
+- Gem den som en secret i organisationen for hvert repository, der publicerer. Der er ingen reserve til `TOKEN_FOR_GITEA`: et repository, der har meldt sig til og ikke har secreten, fejler med en konfigurationsfejl, og et repository, der ikke har meldt sig til, behøver den ikke.
-- `TOKEN_FOR_GITEA` er beskrevet ovenfor med kun `read:repository`. Hvis det genbruges til wikien, skal dets scope hæves, hvilket også giver metadatasynkroniseringen skriveadgang. En separat `TOKEN_FOR_GITEA_WIKI` til en dedikeret bruger holder synkroniseringstokenet skrivebeskyttet. S05 beslutter hvilket, og S03 gemmer secreten.
+- Tokenet skal have scope `write:repository`, og dets bruger skal have skriveadgang til repositories. Gitea har intet scope kun til wikien, så opret tokenet til en dedikeret bruger. S05 godkender scopet, og S03 gemmer secreten.
 - Kald, der foretages: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` og `PATCH /repos/{owner}/{repo}/wiki/...` og, for en side, der ikke længere findes i `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
 - Wikien skal være aktiveret i repositoryets indstillinger. Workflowet nægter at køre, hvis den ikke er det.
-- Wikien er altid lig med `wiki/`: sider, der er redigeret eller tilføjet i Gitea's weboverflade, overskrives eller fjernes ved næste publicering.
+- Sider, der findes i `wiki/`, overskrives altid fra den, så en ændring i Gitea's weboverflade går tabt ved næste publicering. Sider, der kun findes i wikien, fjernes kun, når `wiki/.publish` indeholder ordet `prune`.
 
 ## Udskiftning af et token
 

wiki/Credentials.md

@@ -62,27 +62,29 @@ is ever printed.
 
 ## Wiki publishing secret
 
-The workflow **Publish wiki** (this repository only) copies `wiki/` to the Gitea
+The workflow **Publish wiki** copies `wiki/` to the Gitea wiki of a repository
-wiki when a change to `wiki/` is merged to `main`. It uses `TOKEN_FOR_GITEA_WIKI`
+that has opted in with `wiki/.publish` (see [onboarding.md](Onboarding)). It
-when that secret exists and otherwise reuses `TOKEN_FOR_GITEA`.
+uses its own secret, so the metadata sync token stays read-only.
 
 | Secret | Content | Used for |
 | --- | --- | --- |
-| `TOKEN_FOR_GITEA_WIKI` (optional) | The Gitea token, nothing else | Writing the wiki pages of this repository |
+| `TOKEN_FOR_GITEA_WIKI` | The Gitea token, nothing else | Writing the wiki pages of the repositories of an organization that opt in |
 
-- The token that is used needs scope `write:repository`, and its user needs
+- Store it as a secret of the organization of each repository that publishes.
-  write access to this repository. Gitea has no wiki-only scope.
+  There is no fallback to `TOKEN_FOR_GITEA`: a repository that opted in and has
-- `TOKEN_FOR_GITEA` is documented above with `read:repository` only. Reusing it
+  no such secret fails with a configuration error, and a repository that did
-  for the wiki means raising its scope, which also gives the metadata sync
+  not opt in does not need it.
-  write access. A separate `TOKEN_FOR_GITEA_WIKI` for a dedicated user keeps
+- The token needs scope `write:repository`, and its user needs write access to
-  the sync token read-only. S05 decides which, and S03 stores the secret.
+  the repositories. Gitea has no wiki-only scope, so create the token for a
+  dedicated user. S05 approves the scope and S03 stores the secret.
 - Calls made: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`,
   `GET`, `POST` and `PATCH /repos/{owner}/{repo}/wiki/...` and, for a page that
   no longer exists in `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
 - The wiki must be enabled in the repository settings. The workflow refuses to
   run when it is not.
-- The wiki always equals `wiki/`: pages edited or added in the Gitea web UI are
+- Pages that are in `wiki/` are always overwritten from it, so a change made
-  overwritten or removed on the next publish.
+  in the Gitea web UI is lost on the next publish. Pages that are only in the
+  wiki are removed only when `wiki/.publish` contains the word `prune`.
 
 ## Rotating a token
 

wiki/Credentials.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Credentials.md, source sha256 b810a21a07d5 -->
+<!-- translation of Credentials.md, source sha256 2660f2095b78 -->
 
 > Ini ialah terjemahan [`Credentials`](Credentials). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -48,17 +48,17 @@ Apabila berjaya, log menyatakan `Preflight passed: Gitea and GitHub accepted the
 
 ## Secret untuk menerbitkan wiki
 
-Aliran kerja **Publish wiki** (repositori ini sahaja) menyalin `wiki/` ke wiki Gitea apabila perubahan pada `wiki/` digabungkan ke `main`. Ia menggunakan `TOKEN_FOR_GITEA_WIKI` jika secret itu wujud, dan jika tidak, menggunakan semula `TOKEN_FOR_GITEA`.
+Aliran kerja **Publish wiki** menyalin `wiki/` ke wiki Gitea bagi repositori yang telah memilih menyertainya dengan `wiki/.publish` (lihat [onboarding.md](Onboarding.ms)). Ia menggunakan secret sendiri, supaya token penyegerakan metadata kekal baca sahaja.
 
 | Secret | Kandungan | Digunakan untuk |
 | --- | --- | --- |
-| `TOKEN_FOR_GITEA_WIKI` (pilihan) | Token Gitea, tiada yang lain | Menulis halaman wiki repositori ini |
+| `TOKEN_FOR_GITEA_WIKI` | Token Gitea, tiada yang lain | Menulis halaman wiki bagi repositori dalam organisasi yang memilih menyertainya |
 
-- Token yang digunakan mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori ini. Gitea tidak mempunyai skop untuk wiki sahaja.
+- Simpan sebagai secret organisasi bagi setiap repositori yang menerbitkan. Tiada sandaran kepada `TOKEN_FOR_GITEA`: repositori yang telah memilih menyertainya dan tidak mempunyai secret itu gagal dengan ralat konfigurasi, dan repositori yang tidak memilih tidak memerlukannya.
-- `TOKEN_FOR_GITEA` didokumenkan di atas dengan `read:repository` sahaja. Menggunakannya semula untuk wiki bermakna meningkatkan skopnya, yang juga memberi akses tulis kepada penyegerakan metadata. `TOKEN_FOR_GITEA_WIKI` yang berasingan untuk pengguna khusus mengekalkan token penyegerakan sebagai baca sahaja. S05 memutuskan yang mana, dan S03 menyimpan secret.
+- Token mesti mempunyai skop `write:repository`, dan penggunanya mesti mempunyai akses tulis kepada repositori. Gitea tidak mempunyai skop untuk wiki sahaja, jadi cipta token untuk pengguna khusus. S05 meluluskan skop dan S03 menyimpan secret.
 - Panggilan yang dibuat: `GET /repos/{owner}/{repo}`, `GET /repos/{owner}/{repo}/wiki/pages`, `GET`, `POST` dan `PATCH /repos/{owner}/{repo}/wiki/...` dan, bagi halaman yang tidak lagi wujud dalam `wiki/`, `DELETE /repos/{owner}/{repo}/wiki/page/{name}`.
 - Wiki mesti diaktifkan dalam tetapan repositori. Aliran kerja enggan berjalan jika ia tidak diaktifkan.
-- Wiki sentiasa sama dengan `wiki/`: halaman yang diedit atau ditambah dalam antara muka web Gitea ditimpa atau dibuang pada penerbitan seterusnya.
+- Halaman yang ada dalam `wiki/` sentiasa ditimpa daripadanya, jadi perubahan yang dibuat dalam antara muka web Gitea hilang pada penerbitan seterusnya. Halaman yang hanya ada dalam wiki dibuang hanya apabila `wiki/.publish` mengandungi perkataan `prune`.
 
 ## Menukar token
 

wiki/Home.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 59273bf92278 -->
+<!-- translation of Home.md, source sha256 758940401ac1 -->
 
 > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -23,7 +23,7 @@ Det indeholder i øjeblikket Gitea-workflowet [`sync-github-metadata.yml`](https
 - Repository-secrets:
   - `TOKEN_FOR_GITEA`: Gitea API-token (kun tokenet, ingen JSON)
   - `PAT_FOR_GITHUB`: et GitHub personal access token, der må redigere spejl-repositoryet (kun tokenet, ingen JSON)
-  - `TOKEN_FOR_GITEA_WIKI` (valgfri, kun i dette repository, til workflowet **Publish wiki**): Gitea-token, der kan skrive til repositoryets wiki; hvis den mangler, bruges `TOKEN_FOR_GITEA`, som så skal have skriveadgang
+  - `TOKEN_FOR_GITEA_WIKI` (kun for repositories, der publicerer en wiki, se [tilslutningsvejledningen](Onboarding.da)): et Gitea-token, der kan skrive til wikien, gemt som en secret i repositoryets organisation; der er ingen reserve til `TOKEN_FOR_GITEA`
 
 
 ## Opsætning

wiki/Home.md

@@ -23,7 +23,7 @@ It currently contains the Gitea workflow [`sync-github-metadata.yml`](https://gi
 - Repository secrets:
   - `TOKEN_FOR_GITEA`: Gitea API token (the token only, no JSON)
   - `PAT_FOR_GITHUB`: a GitHub personal access token allowed to edit the mirror repository (the token only, no JSON)
-  - `TOKEN_FOR_GITEA_WIKI` (optional, only in this repository, for the **Publish wiki** workflow): Gitea token that can write the repository wiki; when it is absent, `TOKEN_FOR_GITEA` is used and needs write access
+  - `TOKEN_FOR_GITEA_WIKI` (only for repositories that publish a wiki, see the [onboarding guide](Onboarding)): a Gitea token that can write the wiki, stored as a secret of the repository's organization; there is no fallback to `TOKEN_FOR_GITEA`
 
 
 ## Setup

wiki/Home.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 59273bf92278 -->
+<!-- translation of Home.md, source sha256 758940401ac1 -->
 
 > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -23,7 +23,7 @@ Buat masa ini ia mengandungi aliran kerja Gitea [`sync-github-metadata.yml`](htt
 - Rahsia (secret) repositori:
   - `TOKEN_FOR_GITEA`: token API Gitea (token sahaja, tanpa JSON)
   - `PAT_FOR_GITHUB`: personal access token GitHub yang dibenarkan mengubah suai repositori cermin (token sahaja, tanpa JSON)
-  - `TOKEN_FOR_GITEA_WIKI` (pilihan, hanya dalam repositori ini, untuk aliran kerja **Publish wiki**): token Gitea yang boleh menulis ke wiki repositori; jika tiada, `TOKEN_FOR_GITEA` digunakan dan mesti mempunyai akses tulis
+  - `TOKEN_FOR_GITEA_WIKI` (hanya untuk repositori yang menerbitkan wiki, lihat [panduan menyertakan repositori](Onboarding.ms)): token Gitea yang boleh menulis ke wiki, disimpan sebagai secret organisasi repositori; tiada sandaran kepada `TOKEN_FOR_GITEA`
 
 
 ## Persediaan

wiki/Onboarding.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Onboarding.md, source sha256 17cf1b4c28c6 -->
+<!-- translation of Onboarding.md, source sha256 1d431898754e -->
 
 > Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -30,6 +30,18 @@ Leveringen er automatisk, så et repository behøver ingen kopi af workflowet. S
 6. **Kør det én gang manuelt:** Actions, **Sync GitHub mirror metadata**, Run workflow. Loggen skal slutte med `Synced description and topics to <owner>/<repo>.`, og GitHub-repositoryet skal vise samme beskrivelse og emner.
 7. Hvis det fejler, brug [troubleshooting.md](Troubleshooting.da).
 
+## Publicér en wiki (valgfrit)
+
+Workflowet **Publish wiki** kopierer Markdown-siderne i `wiki/` til repositoryets wiki, når en ændring af `wiki/` flettes til `main`. Det leveres som synkroniseringsworkflowet, men skriver kun, hvor et repository har meldt sig til.
+
+1. Aktivér wikien i repositoryets indstillinger.
+2. Tilføj Markdown-sider til `wiki/`. Filnavnet er sidens navn: `Home.md` er forsiden.
+3. Tilføj markøren `wiki/.publish`. Lad den være tom for kun at oprette og opdatere sider. Skriv det ene ord `prune` i den for også at slette wiki-sider, der ikke findes i `wiki/`, så wikien altid er lig med mappen.
+4. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da).
+5. Flet ændringen til `main`. Loggen skal slutte med `Published <n> page(s) to the wiki of <owner>/<repo>`.
+
+Et repository uden `wiki/.publish` springes over med linjen `No wiki/.publish marker in <owner>/<repo>`: intet bliver skrevet, og der skal ingen secret til.
+
 ## Runners
 
 | Punkt | Værdi |

wiki/Onboarding.md

@@ -49,6 +49,27 @@ Delivery is automatic, so a repository needs no copy of the workflow. Secrets ar
    and topics.
 7. If it fails, use [troubleshooting.md](Troubleshooting).
 
+## Publish a wiki (optional)
+
+The **Publish wiki** workflow copies the Markdown pages in `wiki/` to the
+repository wiki when a change to `wiki/` is merged to `main`. It is delivered
+like the sync workflow, but it writes only where a repository opts in.
+
+1. Enable the wiki in the repository settings.
+2. Add Markdown pages to `wiki/`. The file name is the page name: `Home.md` is
+   the home page.
+3. Add the marker `wiki/.publish`. Leave it empty to create and update pages
+   only. Put the single word `prune` in it to also delete wiki pages that are
+   not in `wiki/`, so the wiki always equals the folder.
+4. Store `TOKEN_FOR_GITEA_WIKI` as a secret of the repository's organization,
+   using the scope in [credentials.md](Credentials).
+5. Merge the change to `main`. The log must end with `Published <n> page(s) to
+   the wiki of <owner>/<repo>`.
+
+A repository without `wiki/.publish` is skipped with the line `No
+wiki/.publish marker in <owner>/<repo>`: nothing is written and no secret is
+needed.
+
 ## Runners
 
 | Item | Value |

wiki/Onboarding.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Onboarding.md, source sha256 17cf1b4c28c6 -->
+<!-- translation of Onboarding.md, source sha256 1d431898754e -->
 
 > Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -30,6 +30,18 @@ Penghantaran adalah automatik, jadi repositori tidak memerlukan salinan aliran k
 6. **Jalankan sekali secara manual:** Actions, **Sync GitHub mirror metadata**, Run workflow. Log mesti berakhir dengan `Synced description and topics to <owner>/<repo>.` dan repositori GitHub mesti menunjukkan penerangan dan topik yang sama.
 7. Jika gagal, gunakan [troubleshooting.md](Troubleshooting.ms).
 
+## Menerbitkan wiki (pilihan)
+
+Aliran kerja **Publish wiki** menyalin halaman Markdown dalam `wiki/` ke wiki repositori apabila perubahan pada `wiki/` digabungkan ke `main`. Ia dihantar seperti aliran kerja penyegerakan, tetapi hanya menulis di tempat repositori telah memilih untuk menyertainya.
+
+1. Aktifkan wiki dalam tetapan repositori.
+2. Tambah halaman Markdown ke `wiki/`. Nama fail ialah nama halaman: `Home.md` ialah halaman utama.
+3. Tambah penanda `wiki/.publish`. Biarkan kosong untuk mencipta dan mengemas kini halaman sahaja. Letakkan satu perkataan `prune` di dalamnya untuk turut memadam halaman wiki yang tiada dalam `wiki/`, supaya wiki sentiasa sama dengan folder itu.
+4. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms).
+5. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published <n> page(s) to the wiki of <owner>/<repo>`.
+
+Repositori tanpa `wiki/.publish` dilangkau dengan baris `No wiki/.publish marker in <owner>/<repo>`: tiada apa-apa ditulis dan tiada secret diperlukan.
+
 ## Runners
 
 | Perkara | Nilai |

wiki/Troubleshooting.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Troubleshooting.md, source sha256 12672b3dde45 -->
+<!-- translation of Troubleshooting.md, source sha256 e8a34cbe7e93 -->
 
 > Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -30,7 +30,8 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
 | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tilføj secreten |
 | `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl |
-| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Kun wiki-publicering: tilføj en af secrets (se [credentials.md](Credentials.da)) |
+| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet har meldt sig til med `wiki/.publish`, men dets organisation har ingen sådan secret; gem den (se [credentials.md](Credentials.da)) |
+| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Kun wiki-publicering: lad markøren være tom, eller skriv kun ordet `prune` i den |
 | `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository |
 | `The wiki is not enabled on <repo>` | configuration | Kun wiki-publicering: aktivér wikien i repositoryets indstillinger |
 | `The wiki source directory ... has no Markdown pages` | configuration | Kun wiki-publicering: `wiki/` er tom eller mangler; intet blev ændret |
@@ -50,6 +51,10 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
 
 `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen.
 
+`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Kørslen af Publish wiki lykkes og skriver intet. Repositoryet har ikke meldt sig til; tilføj `wiki/.publish`, hvis det skal publicere.
+
+`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word 'prune' in wiki/.publish to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre markøren indeholder `prune`.
+
 ## Runner-problemer
 
 Se afsnittet [Runners](Onboarding.da#runners). Kort sagt: hvis kørslen bliver stående som `waiting`, har ingen online runner labelen; hvis jobbet fejler før scriptet, mangler runner-imaget et værktøj.

wiki/Troubleshooting.md

@@ -32,7 +32,8 @@ never starts, or stops before the step) is a **runner** problem.
 | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Add the secret |
 | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
-| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Wiki publishing only: add one of the secrets (see [credentials.md](Credentials)) |
+| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository opted in with `wiki/.publish` but its organization has no such secret; store it (see [credentials.md](Credentials)) |
+| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing only: leave the marker empty, or put only the word `prune` in it |
 | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
 | `The wiki is not enabled on <repo>` | configuration | Wiki publishing only: enable the wiki in the repository settings |
 | `The wiki source directory ... has no Markdown pages` | configuration | Wiki publishing only: `wiki/` is empty or missing; nothing was changed |
@@ -57,6 +58,14 @@ settings.
 synced.` The run succeeds but nothing was synced. Check that the Gitea
 version supports the push mirror API and re-run.
 
+`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
+this repository.` The Publish wiki run succeeds and writes nothing. The
+repository has not opted in; add `wiki/.publish` if it should publish.
+
+`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word
+'prune' in wiki/.publish to delete them.` The run succeeds. Pages that exist
+only in the wiki are left alone unless the marker contains `prune`.
+
 ## Runner problems
 
 See the [Runners](Onboarding#runners) section. In short: if the run stays

wiki/Troubleshooting.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Troubleshooting.md, source sha256 12672b3dde45 -->
+<!-- translation of Troubleshooting.md, source sha256 e8a34cbe7e93 -->
 
 > Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -30,7 +30,8 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
 | `TOKEN_FOR_GITEA is missing or empty.` | configuration | Tambah secret |
 | `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub |
-| `No token for the wiki: set TOKEN_FOR_GITEA_WIKI, or TOKEN_FOR_GITEA.` | configuration | Penerbitan wiki sahaja: tambah salah satu secret (lihat [credentials.md](Credentials.ms)) |
+| `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori telah memilih menyertainya dengan `wiki/.publish` tetapi organisasinya tiada secret itu; simpannya (lihat [credentials.md](Credentials.ms)) |
+| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Penerbitan wiki sahaja: biarkan penanda kosong, atau letakkan hanya perkataan `prune` di dalamnya |
 | `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini |
 | `The wiki is not enabled on <repo>` | configuration | Penerbitan wiki sahaja: aktifkan wiki dalam tetapan repositori |
 | `The wiki source directory ... has no Markdown pages` | configuration | Penerbitan wiki sahaja: `wiki/` kosong atau tiada; tiada apa-apa diubah |
@@ -50,6 +51,10 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
 
 `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula.
 
+`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Larian Publish wiki berjaya dan tidak menulis apa-apa. Repositori belum memilih menyertainya; tambah `wiki/.publish` jika ia sepatutnya menerbitkan.
+
+`<n> page(s) are in the wiki but not in wiki/ and were kept; put the word 'prune' in wiki/.publish to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan penanda mengandungi `prune`.
+
 ## Masalah runner
 
 Lihat bahagian [Runners](Onboarding.ms#runners). Ringkasnya: jika larian kekal `waiting`, tiada runner dalam talian yang mempunyai label itu; jika kerja gagal sebelum skrip, imej runner tiada satu alat.