Skip to content

docs: add VitePress documentation site at ldelements.org#664

Open
ddeboer wants to merge 1 commit into
mainfrom
docs/documentation-site
Open

docs: add VitePress documentation site at ldelements.org#664
ddeboer wants to merge 1 commit into
mainfrom
docs/documentation-site

Conversation

@ddeboer

@ddeboer ddeboer commented Jul 25, 2026

Copy link
Copy Markdown
Member

Adds a VitePress documentation site under docs/, deployed to https://ldelements.org, and makes it the single source of truth for all documentation.

Site

  • Guide: introduction pages (what/when/core concepts/architecture, with hand-drawn Mermaid diagrams), two tutorials (Build a pipeline, Build a search API with a Docker Compose setup), and 13 how-to recipes grouped by concern.
  • Reference: one page per package (all 26), packages and standards overviews, and the existing decision records wired into the sidebar (titles generated from the files at build time).
  • Local search, sitemap, clean URLs, edit links, dark/light themes.

Content migration (ADR 17)

  • All package README content moved into docs/reference/<package>.md; READMEs slimmed to description, installation, at most one example, and a link to the package’s docs page (3,223 → 630 lines total). npm pages stay accurate because they contain little that can go stale.
  • The README’s comparison table and dependency diagram moved into the docs; AGENTS.md and CONTRIBUTING.md record the new policy.

Completeness audit

All packages and four consumer projects (Dataset Register, Dataset Knowledge Graph, LODA pipeline, Linked Open Limburg) were audited against the docs; every finding was verified against source before fixing. Highlights:

  • Corrected factually wrong docs: a documented option that does not exist (pipeline-shacl-sampler timeout), an outdated ItemSelector signature, stale ‘Executor’ terminology, a materialized view that is now a table, a false log-streaming claim, and schema examples that failed the indexer at boot (missing path).
  • Documented previously missing surface: Stage.project, reader template substitution, SparqlUpdateWriter semantics, writer fan-out and standalone use, failure isolation, the full ProgressReporter event table, createQlever() options incl. native mode and the absolute-dataDir requirement (createQlever({mode:'docker'}) silently fails without dataDir (no bind-mount, wrong workdir) #638), QLever’s supported dump formats, registry criteria operators, verdict contracts, maxFacetValues, range facets, the GraphQL pagination contract, and a working TypeScript schema-module bundling recipe.
  • Content from fix(pipeline): fail fast when the provenance store cannot persist records #662 (provenance check(), volume writability) is ported into the docs, since the READMEs that carried it are slimmed here.

Deployment

  • .github/workflows/docs.yml builds the site on every PR (the build fails on dead links) and deploys to GitHub Pages on pushes to main.
  • The Pages site is created with the ldelements.org custom domain attached; DNS already points at GitHub Pages, so the first deployment after merge goes live. HTTPS enforcement follows once the certificate is issued.

- Add a VitePress site under docs/ with a Guide and a Reference for all 26 packages

- Migrate README content into docs/reference; slim READMEs to a summary plus docs link (ADR 17)

- Audit all packages and four consumer projects; fix stale claims and document missing options

- Deploy to GitHub Pages from docs.yml with the ldelements.org custom domain

- Fail the docs build on dead links and run it as a PR check

- Render Mermaid diagrams hand-drawn; add sitemap and local search

- Record the documentation policy in AGENTS.md and CONTRIBUTING.md
@ddeboer
ddeboer force-pushed the docs/documentation-site branch from 536196a to 8cdc2f0 Compare July 25, 2026 19:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant