docs: introduce Docusaurus docs site and simplify wiki#151
Merged
Conversation
nikazzio
added
type:docs
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #151 +/- ##
==========================================
- Coverage 71.01% 70.93% -0.09%
==========================================
Files 153 153
Lines 13229 13229
==========================================
- Hits 9395 9384 -11
- Misses 3834 3845 +11
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a minimal Docusaurus site as the canonical documentation surface, reorganizes docs into a clearer information architecture, and reduces the GitHub Wiki to a short orientation layer that points into the published docs site.
Changes:
- Add a minimal Docusaurus setup (config, sidebars, styling, npm scripts/deps) and a GitHub Pages deploy workflow.
- Reorganize/author docs into
intro/,guides/,reference/,explanation/,project/, andadr/, and simplify legacy hub pages. - Update wiki publishing/sync to rewrite canonical links toward the public docs site and shrink wiki pages to entry-level content.
Reviewed changes
Copilot reviewed 44 out of 46 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| static/img/.gitkeep | Keep Docusaurus static/img directory tracked. |
| src/css/custom.css | Add minimal Docusaurus theme overrides and markdown image styling. |
| sidebars.js | Define Docusaurus sidebar structure for the new docs IA. |
| scripts/sync_wiki.py | Add --docs-base-url and rewrite canonical doc links to the public docs site. |
| scripts/check_docs_integrity.py | Update integrity checks for new docs site structure and required files. |
| package.json | Add npm scripts and Docusaurus dependencies for building the docs site. |
| docusaurus.config.js | Configure Docusaurus site for GitHub Pages deployment and docs behavior. |
| docs/wiki/Troubleshooting.md | New concise wiki troubleshooting page that points into canonical guides. |
| docs/wiki/Studio-Workflow.md | Remove long-form wiki page (moved to canonical docs). |
| docs/wiki/PDF-Export-Profiles.md | Remove long-form wiki page (moved to canonical docs). |
| docs/wiki/Home.md | Rewrite wiki home as an orientation layer pointing to the docs site. |
| docs/wiki/Getting-Started.md | Shorten wiki getting-started and redirect readers to the docs site. |
| docs/wiki/FAQ.md | Trim wiki FAQ and update commands/links to match new model. |
| docs/wiki/Configuration.md | Remove wiki configuration page (moved to canonical docs). |
| docs/wiki/Common-Workflows.md | New short wiki page summarizing common workflows. |
| docs/WIKI_MAINTENANCE.md | Update wiki maintenance model to docs-site canonical + wiki entry layer. |
| docs/reference/runtime-paths.md | New reference page describing runtime path families and defaults. |
| docs/reference/provider-support.md | New reference page documenting provider support matrix and behavior. |
| docs/reference/configuration.md | New configuration overview pointing to detailed key reference. |
| docs/reference/cli.md | New CLI reference documenting primary CLI surface and examples. |
| docs/project/wiki-maintenance.md | New canonical project doc describing wiki publishing rules. |
| docs/project/testing-guide.md | New canonical project doc summarizing test expectations and commands. |
| docs/project/issue-triage.md | New canonical project doc summarizing issue/PR labeling policy. |
| docs/project/contributing.md | New canonical project doc summarizing contribution rules and guardrails. |
| docs/intro/getting-started.md | New canonical “Getting Started” page for docs site. |
| docs/index.md | Rewrite docs landing page into the primary navigation hub for the new IA. |
| docs/guides/troubleshooting.md | New canonical troubleshooting guide. |
| docs/guides/studio-workflow.md | New canonical studio workflow guide. |
| docs/guides/pdf-export.md | New canonical PDF export guide. |
| docs/guides/first-manuscript-workflow.md | New canonical end-to-end “first workflow” guide. |
| docs/guides/discovery-and-library.md | New canonical guide explaining discovery vs. library roles. |
| docs/explanation/storage-model.md | New explanation doc for storage model concepts. |
| docs/explanation/security-and-path-safety.md | New explanation doc outlining safety rules for docs/ops. |
| docs/explanation/job-lifecycle.md | New explanation doc describing download/export job lifecycle. |
| docs/explanation/export-and-pdf-model.md | New explanation doc describing export/PDF decision model. |
| docs/explanation/discovery-provider-model.md | New explanation doc describing provider registry and discovery model. |
| docs/explanation/architecture.md | New architecture summary page with link to deep-dive architecture doc. |
| docs/DOCUMENTAZIONE.md | Reduce legacy user guide to a compact index into the new docs set. |
| docs/assets/screenshots/.gitkeep | Keep screenshots asset directory tracked. |
| docs/adr/0002-docs-site-and-wiki-publishing-model.md | New ADR documenting docs-site + wiki publishing model. |
| docs/adr/0001-docs-information-architecture.md | New ADR documenting the docs information architecture decision. |
| .gitignore | Ignore node_modules/ and .docusaurus/ artifacts. |
| .github/workflows/wiki-sync.yml | Pass --docs-base-url to sync script in CI runs. |
| .github/workflows/docs-site.yml | Add GitHub Pages workflow to build/deploy the docs site. |
| .github/workflows/docs-ci.yml | Build Docusaurus docs in CI and add npm caching/install step. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+58
to
+62
| label: "ADRs", | ||
| items: [ | ||
| "adr/docs-information-architecture", | ||
| "adr/docs-site-and-wiki-publishing-model", | ||
| ], |
| - "static/**" | ||
| - "docusaurus.config.js" | ||
| - "sidebars.js" | ||
| - "package.json" |
Comment on lines
35
to
43
| ```bash | ||
| python scripts/sync_wiki.py --repo owner/repo --dry-run | ||
| ``` | ||
|
|
||
| Publish when dry-run is clean: | ||
|
|
||
| ```bash | ||
| python scripts/sync_wiki.py --repo owner/repo --push | ||
| ``` |
- Add /img/* to .lycheeignore (root-relative Docusaurus static paths) - Move onBrokenMarkdownLinks to top-level config (was no-op inside markdown.hooks) - Point README documentation table to published docs site URL - Update repo homepage to https://nikazzio.github.io/scriptoria/ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- fix check_docs_integrity.py REQUIRED_README_LINKS to match hosted Docusaurus URLs used in README instead of local relative paths - fix .lycheeignore: use proper regex (.*) instead of glob (*) so nikazzio.github.io and img.shields.io patterns are correctly excluded - add /img/.* to .lycheeignore to prevent lychee URL-build errors on root-relative Docusaurus image paths - add fan-in 'ci' job to ci.yml so the protect-main ruleset required status check 'ci' is satisfied; job gates on lint + test results Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Root-relative paths like /img/scriptoria-header.svg cause lychee to fail URL construction before any exclude filter is applied. Adding --base resolves them to absolute GH Pages URLs, which are then caught by the existing nikazzio.github.io/.* pattern in .lycheeignore. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Link checking via lychee is not viable on PRs: the Docusaurus site deploys only from main, so all nikazzio.github.io/* links are permanently 404 during PR review. Removing the job eliminates recurring false failures with no loss of real coverage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
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.
Summary
Introduce a minimal Docusaurus-based canonical docs site, reorganize the documentation into a clearer structure, and reduce the GitHub Wiki to a short orientation layer.
Linked Issues
Closes #150
Governance Checklist
feat:,fix:,docs:,chore:, etc.).type:*label.priority:*label.area:*label.major,minor,patch, orsemver:none).Validation
python3 scripts/check_docs_integrity.pypython3 scripts/check_docs_language.pypython3 scripts/sync_wiki.py --repo nikazzio/scriptoria --source-root docs/wiki --wiki-dir /tmp/scriptoria-wiki-dryrun --docs-base-url https://nikazzio.github.io/scriptoria/ --dry-runnpm run docs:buildNotes