Skip to main content

SCOPE website

Documentation source: website/README.md at revision d127243ba072cb8572df536d40a31be3935e0106.

This Docusaurus site publishes the repository's root README.md and explicitly approved sub-project documentation at https://ftod.github.io/scope/. Each source Markdown file remains the prose authority; generated documentation is never edited directly.

Requirements​

  • Node.js 24 (see .nvmrc)
  • npm
  • Chromium for browser, accessibility, and Lighthouse checks

With nvm, run nvm use. Then install the locked dependencies and browser:

npm ci
npx playwright install --with-deps chromium

Approved public content​

content-map.json assigns all 12 level-two README sections to five ordered documentation pages. subprojects.json is the versioned publication allowlist. It defines each public sub-project, its status and audience, its authoritative tracked Markdown documents, and its namespaced routes. The initial inventory contains:

  • Research Data Collector: collector/README.md and collector/examples/README.md;
  • SCOPE Website: website/README.md.

Directory presence never authorizes publication. To publish another sub-project, add its tracked, reviewed Markdown source and one project/document registration to subprojects.json. Give every record a stable ID, unique position, project-owned route, purpose, audience, status, and primary document. The validator rejects inferred, missing, empty, untracked, symlinked, multiply mapped, unsafe, executable, credential-like, generated, collected-data, fixture, test, and internal-spec sources.

scripts/generate-site-content.mjs validates all 12 root sections and the public inventory, then writes root pages, the sub-project catalog, whole-document project pages, landing data, a coverage report, and a public provenance manifest under .generated/. It rewrites approved relative documentation links to site routes and governed repository-only links to revision-pinned GitHub URLs. Each generation records per-source hashes, structural fingerprints, generated-file hashes, the source revision, and an aggregate public-content SHA-256 digest.

Run source validation, generation, or a read-only output audit with:

npm run validate:sources
npm run generate
npm run validate:content

npm start generates content for local authoring. Production validation calls generation exactly once before npm run build, then npm run audit:artifact checks the static route/file boundary, public manifest, unsafe content canaries, and artifact-tree digest. Files under .generated/ are ignored build inputs and must not be committed.

The publication pipeline only reads approved documentation and builds this static site. It never imports or executes collector code, runs collection examples, contacts OpenAlex, DBLP, ORCID, or arXiv, or reads provider credentials and collected records.

Local development and validation​

npm start
npm run validate:sources
npm run generate
npm run test:unit
npm run validate:content
npm run typecheck
npm run build
npm run audit:artifact
npm run test:e2e
npm run test:lighthouse
npm run test:performance-sample

npm run test:e2e serves the production artifact beneath /scope/ and derives route coverage from the publication manifest. It checks desktop, 390-pixel mobile, keyboard, no-JavaScript, not-found, content, direct fragments, overflow, and axe accessibility behavior. Lighthouse runs three samples for Home, the catalog, the collector guide, and this maintainer guide; median accessibility, crawlability, and two-second first-contentful-paint results are release gates while broader diagnostics remain warnings.

Preview the production artifact at http://127.0.0.1:3000/scope/:

npm run serve -- --host 127.0.0.1

Publication and recovery​

Pull requests targeting main run .github/workflows/site-checks.yml without deployment permission. Pushes to main and manual dispatches run .github/workflows/deploy-pages.yml, which repeats every validation gate, uploads only website/build/, and deploys it through the protected github-pages environment. Official actions are pinned to full commit SHAs. The build summary records source, content, and static-tree digests; a post-deploy check compares the public manifest with the approved revision and opens representative sub-project routes.

A generation, test, or build failure prevents artifact upload and deployment. Recover a bad published revision by reverting its source change through the normal review flow; do not unpublish the Pages site. See the feature quickstart.md for the full validation and recovery drill.

The site is static and read-only. It adds no accounts, comments, forms, analytics, or personal-data collection.