Allow documentation corrections without a GitHub account

.github/workflows/ci.yml

@@ -22,3 +22,7 @@ jobs:
         run: npm ci
       - name: Validate and build
         run: npm run check
+      - name: Verify suggestions service
+        run: npm run test:suggestions && npm run suggestions:check
+      - name: Verify frozen manuals
+        run: npm run test:archives

.github/workflows/deploy.yml

@@ -29,7 +29,11 @@ jobs:
       - name: Validate documentation
         run: npm run check:docs
       - run: npm run test:archives
+      - run: npm run test:suggestions
       - run: npm run build
+        env:
+          VIZARD_SUGGESTIONS_API: ${{ vars.VIZARD_SUGGESTIONS_API }}
+          VIZARD_TURNSTILE_SITE_KEY: ${{ vars.VIZARD_TURNSTILE_SITE_KEY }}
       - name: Assemble frozen release manuals
         run: npm run assemble:archives
         env:

.gitignore

@@ -16,6 +16,10 @@ pnpm-debug.log*
 # environment variables
 .env
 .env.production
+.dev.vars*
+.wrangler/
+*.pem
+services/suggestions/wrangler.local.jsonc
 
 # macOS-specific files
 .DS_Store

CONTRIBUTING.md

@@ -4,11 +4,21 @@ Corrections, clearer explanations, and missing documentation are welcome.
 
 ## Suggest a correction
 
-If you do not want to edit Markdown, open a
+When **Suggest a change** is available on a published page, choose a passage,
+edit its wording, review it, and send. You do not need a GitHub account or
+Markdown knowledge. Use **Describe a problem** for missing information or a
+larger change. Suggestions and explanations are public and reviewed before
+publication. Save the receipt link if you want to check progress.
+
+For contributors who already use GitHub, you can also open a
 [documentation correction](https://github.com/plmn95/vizard-docs/issues/new?template=documentation-correction.yml).
 Include the page URL, what is unclear or incorrect, and the wording you suggest
 when you have it.
 
+If the on-page contribution controls are unavailable, the account-free service
+has not been enabled or is temporarily disabled. The GitHub route below is an
+alternative for people who already have an account.
+
 ## Edit a page on GitHub
 
 Use **Edit page** at the bottom of a published article. GitHub will guide you

README.md

@@ -25,9 +25,15 @@ npm run check
 
 ## Contributing
 
-Small corrections can be made with the **Edit page** link on the published
-site. For larger changes, read [CONTRIBUTING.md](CONTRIBUTING.md) and open a
-pull request.
+When enabled, **Suggest a change** lets readers edit a passage and send it for
+review without a GitHub account. **Describe a problem** accepts broader reports.
+GitHub editing remains available for experienced contributors. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+The account-free service requires separate Cloudflare and GitHub App setup;
+see [setup and operations](services/suggestions/README.md). It stays disabled
+until configured. Run `npm run test:suggestions` for delivery and source-mapping
+tests, and `npm run suggestions:check` to verify the Worker bundle.
 
 ## Manuals shipped with Vizard
 

astro.config.mjs

@@ -1,11 +1,15 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
 import starlight from '@astrojs/starlight';
+import suggestionPassages from './src/lib/suggestions/remark.mjs';
+import { revision, enabled } from './src/lib/suggestions/config.mjs';
 
 const isVercel = process.env.VERCEL === '1';
 
 // https://astro.build/config
 export default defineConfig({
+	markdown: { processor: unified({ remarkPlugins: [[suggestionPassages, { revision, enabled }]] }) },
 	site: isVercel ? 'https://vizard-docs.vercel.app' : 'https://plmn95.github.io',
 	base: process.env.VIZARD_DOCS_BASE || (isVercel ? '/' : '/vizard-docs'),
 	integrations: [
@@ -19,6 +23,7 @@ export default defineConfig({
 			components: {
 				SiteTitle: './src/components/SiteTitle.astro',
 				Footer: './src/components/ManualFooter.astro',
+				EditLink: './src/components/GitHubEditLink.astro',
 			},
 			editLink: {
 				baseUrl: 'https://github.com/plmn95/vizard-docs/edit/main/',