Official documentation for the LongitudeOne Spatial ecosystem, Doctrine integration, spatial types, geometry formats, and standards.
Requirements: Node.js 20 or newer and npm 10 or newer.
npm install
npm run start:localThe start command launches the Docusaurus development server. Open http://localhost:3000/index.html to view the documentation home page.
Build a local preview with fictional legal information:
npm run build:localPreview the built files with:
npm run serveThe local commands require no legal environment variables and generate fictional
legal notices. Their output cannot be deployed. For publication, supply the
reviewed legal configuration and run npm run build.
Open http://localhost:3000/index.html. The preview serves explicit .html
and .md files directly, including index.html; extensionless and directory
routes are rejected. For the Pages configuration, use
http://localhost:3000/spatial-docs/index.html.
The final deployable artifact is public/. Docusaurus uses build/ as an
intermediate directory; .publication-metadata/ retains internal integrity and
asset manifests. Deploy only the validated public/ tree without rebuilding or
transforming its content. Internal manifests, reports, caches and source maps
are excluded from it. Public files use mode 0644 and directories 0755.
npm run build:local and npm run start:local supply the standard production
and preproduction URLs when they are absent, alongside test legal information.
Explicit URL settings are preserved. These helpers must never publish a site.
Set URL_PRODUCTION to the official documentation HTTPS URL for publication builds.
For the development site, also set DOCUSAURUS_DEPLOYMENT=development and
URL_PREPRODUCTION to the GitHub Pages HTTPS origin; the configured project base
path is appended automatically. Missing or invalid values fail generation.
The development announcement links to the configured official documentation URL.
Start with the documentation contribution workflow for writing, validation, pull requests, review and version maintenance.
docs/shared/contains documentation shared across the ecosystem.docs/<library>/v<major>/contains versioned library documentation.docs/standards/,docs/concepts/anddocs/dbms/contain spatial references.- Use portable
.mdsources withtitleanddescriptionfront matter; MDX and raw HTML are not supported in published documentation. inbox/contains drafts that are not yet part of the published site.
npm run build exports published .md pages alongside their HTML counterparts
in public/ and generates a curated root public/llms.txt index plus the complete
public/llms-full.txt context. For example,
public/shared/index.html and public/shared/index.md represent the same document;
there is no public markdown/ prefix.
The internal .generated-markdown/ directory contains generated Markdown with
portable metadata and the matching relative HTML link. Docusaurus copies its
contents directly to the publication root. Source-relative documentation links
and heading anchors are validated before publication; invalid targets fail the
build. See the portable publication contract.
Each HTML page displays View Markdown version directly below its title and
exposes the same relative target through alternate metadata in its head.
A relative describedby head link advertises the deployment’s llms.txt.
Each Markdown page displays View HTML version immediately after front matter.
These links and representation metadata are build-managed; source documents
must not maintain them manually. The build and CI reject missing counterparts,
invalid routes, inconsistent targets, and duplicate switching links.
The actions below each documentation title include View Markdown version and
Edit this page on GitHub. The edit action opens the corresponding source under
docs/ on the repository's main branch, preserving its library, major version
and path. It never edits a generated artifact or redirects historical/Next pages
to the Current major. Both actions have text labels and wrap on small screens.
Pages without a published documentation source have no edit action. For a source
that should not offer editing, set custom_edit_url: null in its front matter;
the Markdown action remains available. Contextual actions are build-managed and
must not be duplicated in document content.
The navbar search searches all published library majors, Standards, Concepts,
DBMS and shared documentation together. Results identify the library, major and
release status; choosing another library or version does not restrict the search.
Use the search field or Ctrl+K (Cmd+K on macOS), then arrow keys and Enter.
Search is local to the browser. npm run build generates one hashed JSON index
beside the site assets; deploy the complete public/ directory from that build.
Preview with npm run serve; the plugin does not generate an index during
npm start. No search account, API key or server-side service is required.
Portable Markdown, drafts, unlisted pages and inbox/ are not indexed.
The pinned @easyops-cn/docusaurus-search-local provider is integrated only in
scripts/local-search.mjs and scripts/search-route-loader.cjs. This adapter
preserves the site's explicit .html routes, adds version context and rejects
an index with missing or unpublished documents. Replace these adapters and the
single theme registration when changing providers; documentation sources and
publication paths do not depend on its index format. Provider upgrades must
pass the local-search regression tests and both publication builds.
Store documentation images, diagrams, schemas, examples and downloads in
static/assets/. See the contributor guide
and asset contract.
Run npm run validate:assets for offline source validation. The normal build
checks the generated manifest and shared bytes in a staging directory before
replacing public/; deployment requires the complete verified directory.
Publication builds require reviewed legal information supplied through environment variables. See the French legal review and configuration checklist for all required values and environment approval. Actual publisher contact details must stay outside Git; rendered notices intentionally make those details public. For local development or validation with fictional, non-deployable information, use:
npm run start:local
npm run build:localThese commands use scripts/with-test-legal.mjs, which supplies fictional values
to the child process. Publication commands continue to require reviewed legal configuration.
Navigation is checked in the final publication gate. See navigation validation for the automated report and desktop/mobile browser journeys.
Production builds generate public/.htaccess deterministically from
config/apache/htaccess.template and scripts/apache-negotiation.mjs.
The validated corpus includes this configuration and deployment transfers it
unchanged to public_html/.htaccess. A missing configuration prevents deployment.
Development Pages builds omit it; GitHub Pages and npm run serve do not provide negotiation.
Apache 2.4 needs mod_rewrite, mod_headers, mod_mime and mod_negotiation
(the latter makes the disabled MultiViews option available).
The hosting directory must allow FileInfo and Options=MultiViews overrides
and permit rewriting (FollowSymLinks or SymLinksIfOwnerMatch). No PHP,
server-side script, variant discovery or per-page server configuration is used.
| Request | Result |
|---|---|
/shared/index.html, any Accept |
HTML |
/shared/index.md, any Accept |
Markdown |
/shared/index, Accept: text/markdown |
Markdown, internal rewrite |
/shared/index, Accept: text/html;q=0.8, text/markdown;q=0.9 |
Markdown, internal rewrite |
/shared/index, equal qualities, */*, or absent Accept |
HTML, internal rewrite |
/shared/index, Accept: application/json or both qualities zero |
406 |
Negotiated responses include Vary: Accept; explicit representations do not
vary by Accept. Qualities use integer thousandths, with exact media ranges
overriding text/*, which overrides */*. Both physical representations must
exist; missing pairs fail as missing resources. Existing files and directories
retain their normal Apache behavior. Representation switching links remain explicit.
Empty parameters (extra semicolons) are ignored. Nonempty media parameters must
match UTF-8, whether they appear before or after the q weight; quoted values
and escaped characters retain their HTTP meaning.
The document root / retains its normal directory index behavior; /index is
the negotiable home resource.
Run the real Apache HTTP integration tests with:
npm run test:apacheThe test starts an isolated unprivileged Apache on a temporary loopback port,
uses the generated production .htaccess, checks response bodies and headers,
and stops the server afterward. CI runs the same suite independently of hosting.
On Linux, install apache2-bin; on macOS the system Apache is used.
Override APACHE_HTTPD and APACHE_MODULES for a different installation.