docs: align with canonical product-pages structure - #83
Merged
rubenvdlinde merged 2 commits intoMay 13, 2026
Conversation
Audit on 2026-05-13 (consolidated report at apps-extra/AUDIT-product- pages-2026-05-13.md) found shillinq's docs/ partially conformant to the canonical product-pages spec shipped at https://design-system.conduction.nl/preview/product-pages/. This change aligns docs/ structurally + Tier-2 config (folder taxonomy, Redocusaurus mount, nl locale, installation.md, em-dash cleanup) per ADR-030. Tier-3 content authoring is tracked separately: #78 UseCases/ + Integrations/ content #79 Dutch translation pass #80 static/oas/shillinq.json OpenAPI spec #81 remaining {{TODO}} cleanup (mostly resolved by #76)
Brings shillinq/docs/ in line with the canonical product-pages layout defined at https://design-system.conduction.nl/preview/product-pages/. Reference implementation: openregister/docs/. Structural (Tier-1) - Rename docs/tutorials/ → docs/user-guide/ (folder + screenshot path). - Move docs/FEATURES.md → docs/Features/index.md (em-dashes fixed). - Move docs/ARCHITECTURE.md → docs/Technical/architecture.md (em-dashes fixed, run-on intro paragraph split into normal prose). - Add empty canonical folders UseCases/ + Integrations/ with draft: true index stubs that point at issue #78. - New docs/installation.md with real Nextcloud install steps (prerequisites, app-store flow, register + chart-of-accounts setup, troubleshooting). - Internal links to ../../ARCHITECTURE.md updated to ../../Technical/architecture.md across 11 tutorial files. - _category_.json labels updated: "Tutorials" → "Guides". Em-dash sweep (REQ-002) - 147 em-dash hits replaced with commas across docs/ (mostly in the user-guide/ files filled in commit #76, plus intro/Architecture/ Features moves). `git grep -E '—' docs/` returns 0. Config (Tier-2) - redocusaurus@^2.0.0 added to docs/package.json (version matches openregister/docs/package.json). - Redocusaurus mounted at /api in docusaurus.config.js, fed by static/oas/shillinq.json. Placeholder OAS shipped so the build does not 404; the real spec lands via issue #80. - Navbar gets an "API Documentation" link to /api, positioned right of "Documentation". - i18n.locales: ['en'] → ['en', 'nl']. No NL markdown ships in this change; the locale dropdown is now available for translators starting work on issue #79. Reversible per ADR-030 escape hatch. Out of scope - No content rewrite of the existing 11 tutorial pages (filled by commit #76 upstream; em-dashes the only edit here). - No NL markdown translation (#79). - No real OpenAPI spec authoring (#80). - No real UseCases/ or Integrations/ content (#78). Build - cd docs && npm install --legacy-peer-deps && npm run build → 0. - Both en and nl locales build successfully. Warnings about /nl/privacy /nl/terms /nl/iso (footer links absent from nl locale) are pre-existing and tracked by #79.
rubenvdlinde
added
documentation
Contributor
Quality Report — ConductionNL/shillinq @
|
| Check | PHP | Vue | Security | License | Tests |
|---|---|---|---|---|---|
| lint | ✅ | ||||
| phpcs | ✅ | ||||
| phpmd | ✅ | ||||
| psalm | ✅ | ||||
| phpstan | ✅ | ||||
| phpmetrics | ✅ | ||||
| eslint | ✅ | ||||
| stylelint | ✅ | ||||
| composer | ✅ | ✅ 100/100 | |||
| npm | ✅ | ✅ 428/428 | |||
| PHPUnit | ✅ | ||||
| Newman | ✅ | ||||
| Playwright | ⏭️ |
Coverage: 0% (0/3 statements)
Quality workflow — 2026-05-13 07:51 UTC
Download the full PDF report from the workflow artifacts.
This was referenced May 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 3 pilot from the 2026-05-13 fleet docs audit (AUDIT report).
Brings
shillinq/docs/in line with the canonical product-pages layout shipped to the design system on 2026-05-13: https://design-system.conduction.nl/preview/product-pages/Reference implementation: openregister/docs.
Scope (Tier-1 + Tier-2 only)
Tier-1 structural
docs/tutorials/→docs/user-guide/(folder + screenshot paths +_category_.jsonlabels).docs/FEATURES.md→docs/Features/index.md.docs/ARCHITECTURE.md→docs/Technical/architecture.md(run-on intro paragraph split into normal prose).docs/UseCases/+docs/Integrations/withdraft: trueindex stubs pointing at issue [product-pages] Author UseCases/ and Integrations/ canonical content #78.docs/installation.mdwith real Nextcloud install steps.../../ARCHITECTURE.md).docs/(mostly from the user-guide prose filled in docs: fill journeydoc tutorial prose #76).git grep -E '—' docs/→ 0 hits.Tier-2 config
redocusaurus@^2.0.0added todocs/package.json(matchesopenregister/docs/package.json)./apiindocusaurus.config.js, fed bystatic/oas/shillinq.json(placeholder OAS shipped so the build does not 404 until [product-pages] Ship static/oas/shillinq.json OpenAPI spec for Redocusaurus #80 lands the real spec).API Documentationlink →/api.i18n.locales: ['en']→['en', 'nl']. No NL markdown ships here; the dropdown is now available for translators starting on [product-pages] Dutch translation pass + re-enable nl locale #79. Reversible per ADR-030 escape hatch.Acceptance
git grep -E '—' docs/returns 0cd docs && npm install --legacy-peer-deps && npm run buildexits 0enlocale buildsnllocale builds/nl/privacy /nl/terms /nl/isofooter links — tracked by #79)installation.mdexists with real install stepsTier-3 follow-ups (not in this PR)
UseCases/+Integrations/canonical contenti18n/nl/static/oas/shillinq.jsonOpenAPI spec{{TODO}}cleanup (largely resolved by docs: fill journeydoc tutorial prose #76)opsx artifacts
openspec/changes/docs-product-pages-conformance/proposal.mdopenspec/changes/docs-product-pages-conformance/design.mdopenspec/changes/docs-product-pages-conformance/specs/docs/spec.mdopenspec/changes/docs-product-pages-conformance/tasks.mdNotes for reviewer
Editreplace_allwith the unambiguous' — '(space-em-space) pattern. Replacements are mostly,(comma). A few comment lines indocusaurus.config.jsgot hand-edited to split into two sentences instead.static/oas/shillinq.jsonis intentionally a minimal placeholder so the build does not 404. The real spec lands via [product-pages] Ship static/oas/shillinq.json OpenAPI spec for Redocusaurus #80.{{TODO}}stubs that no longer exist; PR scope was adjusted accordingly.Closes #81 (after merge).