# AIPOCH Open-Science Documentation
This repository contains the official operating and reproducibility documentation for [AIPOCH Open-Science](https://github.com/aipoch/open-science), built with [Docusaurus](https://docusaurus.io/).
English is the default language at `/docs/`; Simplified Chinese is available at `/docs/zh-Hans/`. Nine locales share the content framework. English and Simplified Chinese are the reviewed source editions; six additional editions remain automatic translation drafts. See [translation status and maintenance](i18n/README.md) and [contribution instructions](CONTRIBUTING.md).
## Content structure
- `docs/` contains the English documentation source; `docs/intro.mdx` is served at `/docs/intro/`.
- `i18n/<locale>/docusaurus-plugin-content-docs/current/` contains translated documentation with the same file structure as `docs/`.
- `sidebars.js` organizes documents into Guides, Workflows, Explore tools, Skills, Specialists, and Reference, with one section per document and stable document and category URLs.
- `src/theme/DocSidebarItems/` renders the desktop and mobile section switcher. Section labels are translated in each locale's `docusaurus-plugin-content-docs/current.json`.
- `static/img/open-science/` contains screenshots captured from a running Open-Science installation.
- `src/pages/` and `src/css/` contain the localized home page and AIPOCH theme changes.
- `i18n.config.mjs` defines the default language and every published locale.
- `scripts/check-english.mjs` keeps the README and default source content in English.
- `scripts/check-i18n.mjs` checks document parity and required interface translations.
## Run locally
Use Node.js 20 or later.
```bash
npm ci
npm start
```
The development server opens [http://localhost:3000/docs/](http://localhost:3000/docs/). Development commands serve one language at a time: `npm start` and `start:en` serve English; `start:zh` serves Simplified Chinese. The other language is unavailable on that development port.
```bash
npm run start:en
npm run start:zh
```
For a preview with working language switching and search, build all configured languages and serve them together. Stop any development preview already using port 3025 first:
```bash
npm run build
npm run serve -- --host 127.0.0.1 --port 3025 --no-open
```
Open [English](http://127.0.0.1:3025/docs/intro/) or [Simplified Chinese](http://127.0.0.1:3025/docs/zh-Hans/intro/). Do not add `--locale` to this build. After editing content, rebuild and refresh the page to update this preview.
Test all published languages before releasing:
```bash
npm run check
npm run build
node --test tests/*.test.mjs
npm run serve
```
With a local Nginx binary, also run the isolated serving checks:
```bash
python3 tests/nginx-seo.py --nginx /absolute/path/to/nginx
```
This test uses a temporary directory and loopback port to check relative
redirects, the legacy sitemap and multilingual index endpoints, and every sitemap page response.
## Main-site integration and release boundary
The Wiki owns only `/docs` and `/docs/...` on the shared AIPOCH origin. Keep `baseUrl` at `/docs/`, docs `routeBasePath` at `/`, and use Wiki routing only inside this boundary. The navbar logo returns to the current origin's `/` through normal document navigation. Client storage must remain namespaced; the Wiki does not share the main site's router or application state. See [the integration contract](AGENTS.md).
Contribute through a review branch and a pull request to `main`. The existing container workflow publishes only from `main`. Branch review and local builds do not deploy; merging, publishing and live configuration changes follow the authorization process in `AGENTS.md`.
The inherited Docker/Nginx runtime retains `/sitemap` for the English sitemap and `/sitemap-index` for the generated multilingual index. The new locale-sitemap plugin generates `build/sitemap-index.xml` from the locale registry. Local Docusaurus preview checks do not establish production gateway behavior.
## Edit documentation
Add or update a Markdown file under `docs/`, then register its document ID in the appropriate section of `sidebars.js`. Store product captures in `static/img/open-science/` and reference them with a public path:
```md
```
Run `npm run check` before committing. The production build runs the same checks and stops when default source content contains Chinese text, a translated document is missing, or a required interface translation is absent.
## Local full-text search
The navbar search indexes document titles, headings, and body text in each configured
documentation language. Results stay within the current documentation locale;
sidebar draft outlines are not indexed as finished articles. Use Cmd+K or
Ctrl+K to focus search, and open the full results page for additional matches.
Search indexes are generated by `npm run build`, so rebuild after content edits
and use `npm run serve` to test search locally. No search service account is
required. Run `node --test tests/*.test.mjs` after building to validate body
matches, locale isolation, and target routes.
## Plain-text documentation exports
`npm run build` generates `llms-full.txt` for every built documentation locale:
English at `/docs/llms-full.txt` and translated editions beneath their locale
paths, such as `/docs/zh-Hans/llms-full.txt`. The existing `llms.txt` remains the
short page index and links to the English full text.
The export reads the rendered documentation article bodies from the same build
as the website. It retains headings, code, tables, links, image descriptions,
platform-specific instructions, source URLs, and available document modification
dates. Navigation, search pages, redirects, and interface controls are excluded.
Product versions and translation-status notices remain as stated in each article;
the export does not replace them with a global latest version or build date.
Generated text belongs in `build/`, not in version control. Rebuild after content
changes; single-locale builds regenerate only that locale's full text. Run
`node --test tests/llms-full.test.mjs` for conversion and generated-output checks.
These are additional static files inside the existing `/docs/` ownership boundary;
no proxy, domain, deployment, or application-runtime configuration is required.
## SEO metadata maintenance
When a document changes substantively, update its `last_update.date` in front
matter to the actual content modification date (`YYYY-MM-DD`). Keep dates
independent for English and Chinese. Do not replace them with build or deploy
dates. Explicit dates are required because Docker builds do not contain Git
history. Generated category pages and the React home page omit `lastmod`
when no explicit source date is available; the sitemap never queries Git.
`/docs/sitemap-index.xml` lists all configured locale sitemaps. The build generates this index from `i18n.config.mjs`; no static list needs to be maintained. The container's `/sitemap-index` endpoint serves it, while `/sitemap` continues to serve `/docs/sitemap.xml`. A main-site sitemap consumer must discover the multilingual index or its child sitemaps to include every language.
Each locale sitemap also carries `xhtml:link` alternate references for every
document, including the `x-default` English URL. Client-side search routes are
excluded from the sitemap because they do not represent indexable content.
The Wiki owns only `/docs` routes. The shared site's root `/robots.txt` remains
owned by the main site and is not emitted by this repository.
After a production build, verify that canonical, hreflang, Open Graph URLs,
and all locale sitemaps consistently use HTTPS URLs with trailing slashes.
Check a fresh container build without Git history to verify document `lastmod`
values. At the public origin, check that a slashless Docs URL redirects directly
to the HTTPS trailing-slash URL, and that every sitemap URL returns HTTP 200.
## Add another language
1. Add the Docusaurus locale code, label, HTML language, and direction to `i18n.config.mjs`.
2. Run `npm run write-translations -- --locale <locale>` to create the shared interface files.
3. Copy `docs/` to `i18n/<locale>/docusaurus-plugin-content-docs/current/` and keep every relative path unchanged.
4. Translate the copied documents and interface message values.
5. Verify the generated `build/sitemap-index.xml` includes the new locale sitemap.
6. Build the site and inspect the new locale locally before publishing.
## Content ownership and editorial checks
Keep one primary explanation for each operation in both languages. Other
articles should link to that explanation and describe only their own task.
| Content | Primary article |
| --- | --- |
| Connector setup, bindings and configuration transfer | `guides/connectors` |
| Choosing a built-in, local or remote integration | `tools/mcp` |
| Creating and managing service secrets | `tools/credentials` |
| Choosing a scientific data source | `tools/databases` |
| Exact built-in operation fields and examples | `reference/connector-operations` |
| File ownership, editing and saved revisions | `guides/files` |
| Common preview controls and ordinary document readers | `guides/previews` |
| Table interpretation and full-dataset checks | `tools/tables` |
| Sequence, structure and molecule viewing | `tools/viewers` |
| Specialist installation, import, export and maintenance | `specialists/manage` |
| Methods, PCA, matrix and reanalysis examples | `workflows/extend-analysis` |
| Public example inputs, hashes and QC baselines | `reference/example-data` |
Write the user's action, expected result and recovery steps before example
evidence. Keep test chronology in the internal audit records. Preserve actual
limitations; a source review or a successful preview does not prove execution.
Introduce shared example data once, then link to it. Keep product release
history in Changelog rather than repeating version announcements in tutorials.
Retired articles belong in `src/data/legacy-doc-redirects.json`, not in duplicate
Markdown pages. Moved section bookmarks belong in
`src/data/moved-doc-fragments.json`. Rebuild all locales and run
`node --test tests/search-index.test.mjs` to check search ownership, legacy
redirects and moved section destinations.
## Related repositories
- [AIPOCH Open-Science](https://github.com/aipoch/open-science)
- [Open-Science Wiki](https://github.com/aipoch/openscience-wiki)