From fcc37241b9b6134d2ad6d5575a7d340046031bf6 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 2 Jul 2025 11:28:29 +0200 Subject: [PATCH 01/15] Update version to 2025.07 (#131) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 6d6437e..85c019d 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.06' +version: '2025.07' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 22d6641fa6b985963c9e893fafe9e98e7427e9c0 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 31 Jul 2025 15:06:50 +0200 Subject: [PATCH 02/15] Update antora.yml to 2025.08 (#133) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 85c019d..1d81b96 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.07' +version: '2025.08' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From c6c8dbbb83c63c742985f9ee5e3e35645d15c585 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 2 Sep 2025 14:09:05 +0200 Subject: [PATCH 03/15] Update antora.yml to 2025.09 (#135) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 1d81b96..d8f6a66 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.08' +version: '2025.09' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 18212cdf7fa2c33fdda80758cd3f4fc3216bc04c Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Mon, 29 Sep 2025 13:42:11 +0200 Subject: [PATCH 04/15] Update version to 2025.10 (#137) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index d8f6a66..a9a90e7 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.09' +version: '2025.10' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 521968f7c4cae50bd0022bed1f334c0cf861da26 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 31 Oct 2025 14:57:31 +0100 Subject: [PATCH 05/15] Update to 2025.11 (#138) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index a9a90e7..4eb6ede 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.10' +version: '2025.11' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 5010a9b49075b502eae77151732c5f432f6df5f8 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 22 Dec 2025 16:09:53 +0100 Subject: [PATCH 06/15] Update antora.yml to 2025.12 (#141) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 4eb6ede..279523f 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.11' +version: '2025.12' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 7ddfa62ccf59fa9097517faced3ede553d4e688b Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 16 Jan 2026 15:45:28 +0100 Subject: [PATCH 07/15] Update antora.yml to 2026.01 (#143) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 279523f..80fee61 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2025.12' +version: '2026.01' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 762e02d3d5fa77dfead148ea18b656c19ac250f1 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 4 Feb 2026 14:50:40 +0100 Subject: [PATCH 08/15] DOCS-279 Bump version to 2026.02 (#145) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 80fee61..e82dac6 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2026.01' +version: '2026.02' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 9e6493f83b8d0ae1d60df7a54de23fa22bdfc177 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 12 Feb 2026 11:44:40 +0000 Subject: [PATCH 09/15] Change copyright: 2025 to copyright: 2026 (#148) --- preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/preview.yml b/preview.yml index c585b13..ab74c0d 100644 --- a/preview.yml +++ b/preview.yml @@ -43,7 +43,7 @@ asciidoc: includePDF: false nonhtmloutput: "" experimental: '' - copyright: 2025 + copyright: 2026 common-license-page-uri: https://neo4j.com/docs/license/ partials: ROOT:partial$@ # attributes for doc links to other manuals in preview playbook From f79ff18bfb7bd0fe1bc0e13d8f406fbc6f8bb35c Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 6 Mar 2026 14:46:25 +0000 Subject: [PATCH 10/15] Update the version to 2026.03 (#153) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index e82dac6..79db589 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2026.02' +version: '2026.03' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From a6515a81c87aae34d4676bff16871368e92d9db8 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Thu, 2 Apr 2026 14:18:00 +0100 Subject: [PATCH 11/15] Update the version to 2026.04 (#155) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 79db589..e271dde 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2026.03' +version: '2026.04' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc From 69a15b741bacda2cfec615452534674ad424e443 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Wed, 8 Apr 2026 16:47:40 +0300 Subject: [PATCH 12/15] Add a note that cluster status endpoints are not deprecated (#156) --- modules/ROOT/pages/endpoints.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/modules/ROOT/pages/endpoints.adoc b/modules/ROOT/pages/endpoints.adoc index 0da4591..03d82b9 100644 --- a/modules/ROOT/pages/endpoints.adoc +++ b/modules/ROOT/pages/endpoints.adoc @@ -4,6 +4,12 @@ This page contains a list of the endpoints that the HTTP API provides, plus pointers to other HTTP endpoints available on a Neo4j server. +[NOTE] +==== +The cluster status endpoints are not deprecated and will continue working. +See link:{neo4j-docs-base-uri}/operations-manual/current/clustering/monitoring/endpoints/[Clustering -> Monitoring -> Monitor cluster endpoints for status information] for more information. +==== + [cols="2m, 3"] |=== |Endpoint location |Description From bee530cd96c1e785faf0a827a80d1bc616097e59 Mon Sep 17 00:00:00 2001 From: Reneta Popova Date: Fri, 10 Apr 2026 16:36:28 +0300 Subject: [PATCH 13/15] Update the HTTP API docs to reflect the correct deprecations (#159) Replaces #158 --- .../pages/authentication-authorization.adoc | 7 ++++ modules/ROOT/pages/bookmarks.adoc | 6 ++++ modules/ROOT/pages/endpoints.adoc | 36 +++++++++---------- modules/ROOT/pages/headers.adoc | 10 +++--- modules/ROOT/pages/index.adoc | 4 +-- modules/ROOT/pages/profile-query.adoc | 6 ++++ modules/ROOT/pages/query-statistics.adoc | 6 ++++ modules/ROOT/pages/query.adoc | 6 ++++ modules/ROOT/pages/result-formats.adoc | 6 ++++ modules/ROOT/pages/routing.adoc | 6 ++++ modules/ROOT/pages/transactions.adoc | 6 ++++ 11 files changed, 72 insertions(+), 27 deletions(-) diff --git a/modules/ROOT/pages/authentication-authorization.adoc b/modules/ROOT/pages/authentication-authorization.adoc index ee75503..48ef84e 100644 --- a/modules/ROOT/pages/authentication-authorization.adoc +++ b/modules/ROOT/pages/authentication-authorization.adoc @@ -1,5 +1,12 @@ = Authorize requests +[NOTE] +==== +The process for authorizing requests to the Neo4j HTTP API is not deprecated and will continue working. +However, all the examples are deprecated as of Neo4j 5.26. +Use the same principles to authorize requests to the HTTP Query API instead, as described in link:{neo4j-docs-base-uri}/query-api/current/authentication-authorization/[Query API -> Authorize requests]. +==== + Unless authentication is disabled on the server, all requests must be authorized using the login credentials of a valid user. Request are authorized through an `Authorization` header. diff --git a/modules/ROOT/pages/bookmarks.adoc b/modules/ROOT/pages/bookmarks.adoc index 3a89852..ed52c3b 100644 --- a/modules/ROOT/pages/bookmarks.adoc +++ b/modules/ROOT/pages/bookmarks.adoc @@ -1,5 +1,11 @@ = Coordinate transactions and enforce causal consistency +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/bookmarks/[Query API -> Coordinate transactions and enforce causal consistency] for details on how to use bookmarks with the Query API. +==== + When working with a cluster, _bookmarks_ allow you to chain transactions and enforce <>. A bookmark is a token that represents some state of the database. By passing one or multiple bookmarks along with a query, the server will make sure that the query does not get executed before the represented state(s) have been established. diff --git a/modules/ROOT/pages/endpoints.adoc b/modules/ROOT/pages/endpoints.adoc index 03d82b9..df6e42f 100644 --- a/modules/ROOT/pages/endpoints.adoc +++ b/modules/ROOT/pages/endpoints.adoc @@ -6,8 +6,10 @@ This page contains a list of the endpoints that the HTTP API provides, plus poin [NOTE] ==== -The cluster status endpoints are not deprecated and will continue working. +The cluster status endpoints and the Discovery API are not deprecated and will continue working. See link:{neo4j-docs-base-uri}/operations-manual/current/clustering/monitoring/endpoints/[Clustering -> Monitoring -> Monitor cluster endpoints for status information] for more information. + +For a list of the endpoints that the Query API provides, plus pointers to other HTTP endpoints available on a Neo4j server, see link:{neo4j-docs-base-uri}/query-api/current/endpoints/[Query API -> Endpoints]. ==== [cols="2m, 3"] @@ -30,23 +32,16 @@ For more information, see xref:transactions.adoc#_execute_queries[Run transactio |/db//tx//commit |To commit an open transaction with ID ``. + For more information, see xref:transactions.adoc#_commit_a_transaction[Run transactions -> Commit a transaction]. - -|/dbms/cluster -|Status endpoint to assist with rolling upgrades. + -For more information, see link:{neo4j-docs-base-uri}/operations-manual/current/clustering/monitoring/endpoints/#clustering-http-endpoints-status[Clustering -> Monitoring -> Monitor cluster endpoints for status information]. - -|/db//cluster -|Status endpoint to assist with rolling upgrades. + -For more information, see link:{neo4j-docs-base-uri}/operations-manual/current/clustering/monitoring/endpoints/#clustering-http-endpoints-status[Clustering -> Monitoring -> Monitor cluster endpoints for status information]. - |=== The overall flow of the API is illustrated below, with each box representing a separate HTTP request: image::http-cypher-transaction-api-flow.png[title="HTTP API flow"] + [[discovery-api]] == Retrieve the endpoints list with the Discovery API +label:deprecated[Not deprecated] To obtain a list of available endpoints on your installation, together with some basic server information, you may send an un-authenticated `GET` request to the server root. @@ -66,16 +61,17 @@ Accept: application/json [source, JSON] ---- { - "bolt_routing": "neo4j://localhost:7687", - "dbms/cluster": "http://localhost:7474/dbms/cluster", - "db/cluster": "http://localhost:7474/db/{databaseName}/cluster", - "transaction": "http://localhost:7474/db/{databaseName}/tx", - "bolt_direct": "bolt://localhost:7687", - "neo4j_version": "5.12.0", - "neo4j_edition": "enterprise", - "auth_config": { - "oidc_providers": [] - } + "bolt_routing": "neo4j://localhost:7687", + "query": "http://localhost:7474/db/{databaseName}/query/v2", + "dbms/cluster": "http://localhost:7474/dbms/cluster", + "db/cluster": "http://localhost:7474/db/{databaseName}/cluster", + "transaction": "http://localhost:7474/db/{databaseName}/tx", + "bolt_direct": "bolt://localhost:7687", + "neo4j_version": "2026.03", + "neo4j_edition": "enterprise", + "auth_config": { + "oidc_providers": [] + } } ---- ==== diff --git a/modules/ROOT/pages/headers.adoc b/modules/ROOT/pages/headers.adoc index 4816174..ae77d12 100644 --- a/modules/ROOT/pages/headers.adoc +++ b/modules/ROOT/pages/headers.adoc @@ -9,8 +9,8 @@ This page contains a full list of headers you may use to tweak the HTTP API beha |Header |Description |Accept -|Desired format of the response body. + -Possible values are `application/json` (default), `application/vnd.neo4j.jolt-v2`, or `application/vnd.neo4j.jolt-v2+json-seq`. + +|label:deprecated[Not deprecated] Desired format of the response body. + +Possible values are `application/json` (default), `application/vnd.neo4j.jolt-v2`, or `application/vnd.neo4j.jolt-v2+json-seq`.footnote:[The `application/json` format is not deprecated, but the JOLT formats are deprecated.] + For more information, see xref:result-formats.adoc[]. |Access-Mode @@ -19,7 +19,7 @@ Possible values are `READ` or `WRITE` (default). + For more information, see xref:routing.adoc[]. |Authorization -|Authentication credentials to authorize the request. + +|label:deprecated[Not deprecated] Authentication credentials to authorize the request. + For more information, see xref:authentication-authorization.adoc[]. |Bookmarks @@ -27,7 +27,7 @@ For more information, see xref:authentication-authorization.adoc[]. For more information, see xref:bookmarks.adoc[]. |Content-Type -|The format of the request body. + +|label:deprecated[Not deprecated] The format of the request body. + The only possible value is `application/json`. |=== @@ -40,7 +40,7 @@ The only possible value is `application/json`. |Content-Type |The format of the response body (matches the `Accept` request header). + -Possible values are `application/json`, `application/vnd.neo4j.jolt-v2`, or `application/vnd.neo4j.jolt-v2+json-seq`. + +Possible values are `application/json` (not deprecated), `application/vnd.neo4j.jolt-v2`, or `application/vnd.neo4j.jolt-v2+json-seq`.footnote:[The `application/json` format is not deprecated, but the JOLT formats are deprecated.] For more information, see xref:result-formats.adoc[]. |=== diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 63613c4..0b77cf8 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -5,8 +5,8 @@ [WARNING] ==== -The HTTP API is not available on <>. -Use the link:{neo4j-docs-base-uri}/query-api/current/[Query API] instead. +The transactional HTTP API is deprecated and replaced by the Query API. +See the link:{neo4j-docs-base-uri}/query-api/current/[Neo4j Query API] documentation for more information. ==== The Neo4j HTTP API allows to execute a series of Cypher statements against a Neo4j server through HTTP requests. diff --git a/modules/ROOT/pages/profile-query.adoc b/modules/ROOT/pages/profile-query.adoc index c0968c0..f9b6aa7 100644 --- a/modules/ROOT/pages/profile-query.adoc +++ b/modules/ROOT/pages/profile-query.adoc @@ -1,5 +1,11 @@ = Profile queries +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/profile-query/[Query API -> Profile queries] for details on how to profile queries with the Query API. +==== + If a query is prepended with `EXPLAIN`, the server will return the _execution plan_ it would use to run it, but not actually execute it. On the other hand, if a query is prepended with `PROFILE`, the server will return the execution plan _and_ the corresponding query result. diff --git a/modules/ROOT/pages/query-statistics.adoc b/modules/ROOT/pages/query-statistics.adoc index da39de9..efed1c1 100644 --- a/modules/ROOT/pages/query-statistics.adoc +++ b/modules/ROOT/pages/query-statistics.adoc @@ -1,5 +1,11 @@ = Retrieve query statistics +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/query-counters/[Query API -> Retrieve query counters] for details on how to retrieve query counters with the Query API. +==== + If `includeStats` is set to `true` for a statement, the server returns query statistics (also known as query counters) alongside the query result. Statistics give insights into how the status of the database was altered by the query. ==== diff --git a/modules/ROOT/pages/query.adoc b/modules/ROOT/pages/query.adoc index a0f8910..5935246 100644 --- a/modules/ROOT/pages/query.adoc +++ b/modules/ROOT/pages/query.adoc @@ -1,5 +1,11 @@ = Query the database +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/query/[Query API -> Query the database] for details on how to run queries with the Query API. +==== + To run a query on a database, submit a `POST` request to the following endpoint: ---- diff --git a/modules/ROOT/pages/result-formats.adoc b/modules/ROOT/pages/result-formats.adoc index a7067f1..af10a91 100644 --- a/modules/ROOT/pages/result-formats.adoc +++ b/modules/ROOT/pages/result-formats.adoc @@ -2,6 +2,12 @@ = Result formats +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/plain-json/[Query API -> Plain JSON] and link:{neo4j-docs-base-uri}/query-api/current/typed-json/[Query API -> Typed JSON] for details on how to receive query results in different formats with the Query API. +==== + Responses can return queried data in three formats: JSON, Jolt, or graph. == JSON diff --git a/modules/ROOT/pages/routing.adoc b/modules/ROOT/pages/routing.adoc index a9b8192..ab4af4f 100644 --- a/modules/ROOT/pages/routing.adoc +++ b/modules/ROOT/pages/routing.adoc @@ -1,5 +1,11 @@ = Route queries to read cluster members +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/routing/[Query API -> Route queries to read cluster members] for details on how to route queries to read cluster members with the Query API. +==== + In a cluster environment, all queries are routed to writer members by default. To ensure efficient load balancing, you should send queries that contain only read statements to the cluster readers. You can do so by adding the header `Access-Mode: READ` to the request (the default is `WRITE`). diff --git a/modules/ROOT/pages/transactions.adoc b/modules/ROOT/pages/transactions.adoc index 2864863..76a69fe 100644 --- a/modules/ROOT/pages/transactions.adoc +++ b/modules/ROOT/pages/transactions.adoc @@ -1,5 +1,11 @@ = Run transactions +[NOTE] +==== +The transactional HTTP API is deprecated and replaced by the HTTP Query API. +See link:{neo4j-docs-base-uri}/query-api/current/transactions/[Query API -> Run transactions] for details on how to use transactions with the Query API. +==== + Use transactions to group together related queries which work together to achieve a single logical database operation. As Neo4j is <> compliant, queries within a <> will either be executed as a whole or not at all: you cannot get a part of the transaction succeed and another fail. From 869e1ab3ba7faa3dba56263f65d4c72fa5cda0c3 Mon Sep 17 00:00:00 2001 From: Neil Dewhurst Date: Wed, 22 Apr 2026 11:13:23 +0100 Subject: [PATCH 14/15] Update to latest workflows and actions (#162) --- .github/workflows/docs-deploy-surge.yml | 139 ++++++++++++++++++----- .github/workflows/docs-generate-html.yml | 97 ++++++++++++++++ .github/workflows/docs-pr-checks.yml | 21 ++-- .github/workflows/docs-teardown.yml | 13 ++- package.json | 63 ++++++---- preview.yml | 11 +- publish.yml | 13 ++- 7 files changed, 281 insertions(+), 76 deletions(-) create mode 100644 .github/workflows/docs-generate-html.yml diff --git a/.github/workflows/docs-deploy-surge.yml b/.github/workflows/docs-deploy-surge.yml index 2399928..9278cd6 100644 --- a/.github/workflows/docs-deploy-surge.yml +++ b/.github/workflows/docs-deploy-surge.yml @@ -1,8 +1,8 @@ # Use this starter workflow to deploy HTML generated by Antora to surge.sh # Docs are published at --.surge.sh -# +# # By default, this workflow runs on completion of a workflow called "Verify docs PR" -# +# # This workflow expects the triggering workflow to generate an artifact called "docs" # - update the reference to "docs" and "docs.zip" in this workflow if your triggering workflow generates an artifact with a different name @@ -10,6 +10,11 @@ name: "Deploy docs preview" +permissions: + actions: read + contents: read + pull-requests: write + on: workflow_run: workflows: ["Verify docs PR"] @@ -17,18 +22,35 @@ on: - completed jobs: - publish-docs: - # Uncomment this if statement to deploy only when the PR builds cleanly - # if: github.event.workflow_run.conclusion == 'success' + # [Optional] Restrict automatic dpeloyment to PRs from the upstream repo + # For fork PRs, requires manual approval via the "preview" environment. + # For PRs from the main repository this job is skipped and deploy-docs runs immediately. + # Setup: create a "preview" environment in Settings → Environments with required reviewers. + # approve-fork: + # if: github.event.workflow_run.head_repository.full_name != github.repository + # environment: preview + # runs-on: ubuntu-latest + # steps: + # - name: Fork PR approved for deployment + # run: echo "Approved" + + deploy-docs: + # needs: [approve-fork] + # Run when approve-fork succeeded (fork, approved) or was skipped (non-fork). + # Uncomment the conclusion check to deploy only when the PR builds cleanly: + # && github.event.workflow_run.conclusion == 'success' + # if: | + # always() && + # (needs.approve-fork.result == 'success' || needs.approve-fork.result == 'skipped') runs-on: ubuntu-latest steps: - name: "Download built documentation" - uses: actions/github-script@v7 + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8 env: RUN_ID: ${{ github.event.workflow_run.id }} - WORKSPACE: ${{ github.workspace }} + ARTIFACT_DIR: ${{ runner.temp }}/artifacts with: script: | var artifacts = await github.rest.actions.listWorkflowRunArtifacts({ @@ -47,7 +69,8 @@ jobs: archive_format: 'zip', }); var fs = require('fs'); - fs.writeFileSync('${{ env.WORKSPACE }}/docs.zip', Buffer.from(downloadDocs.data)); + fs.mkdirSync(process.env.ARTIFACT_DIR + '/docs', { recursive: true }); + fs.writeFileSync(process.env.ARTIFACT_DIR + '/docs/docs.zip', Buffer.from(downloadDocs.data)); var matchArtifactChangelog = artifacts.data.artifacts.filter((artifact) => { return artifact.name == "changelog" @@ -58,27 +81,68 @@ jobs: artifact_id: matchArtifactChangelog.id, archive_format: 'zip', }); - fs.writeFileSync('${{ env.WORKSPACE }}/changelog.zip', Buffer.from(downloadChangelog.data)); + fs.mkdirSync(process.env.ARTIFACT_DIR + '/changelog', { recursive: true }); + fs.writeFileSync(process.env.ARTIFACT_DIR + '/changelog/changelog.zip', Buffer.from(downloadChangelog.data)); + + - id: suspicious-path-check + name: Suspicious paths check + env: + ARTIFACT_DIR: ${{ runner.temp }}/artifacts/docs + run: | + cd "$ARTIFACT_DIR" + if unzip -l docs.zip | grep -q "\.\./"; then + exit 1 + fi + + - id: hidden-files-check + name: Hidden files check + env: + ARTIFACT_DIR: ${{ runner.temp }}/artifacts/docs + run: | + cd "$ARTIFACT_DIR" + HIDDEN_FILES=$(find . -type f -name ".*" | wc -l) + if [ "$HIDDEN_FILES" -ne 0 ]; then + echo "Security Alert: Unexpected hidden files detected!" + exit 1 + fi - id: unzip-docs - run: unzip docs.zip + name: Unzip docs artifact + env: + ARTIFACT_DIR: ${{ runner.temp }}/artifacts/docs + run: | + cd "$ARTIFACT_DIR" + unzip docs.zip - - id: get-top-dir + - id: find-changelog + name: Get changelog run: | - root=$(ls -d */index.html | sed -r 's/(.*)\/index\.html/\1/') - echo "top-dir=$root" >> $GITHUB_OUTPUT + if [ -f "${{ runner.temp }}/artifacts/changelog/changelog.zip" ]; then + echo "has-changelog=true" >> $GITHUB_OUTPUT + else + echo "has-changelog=false" >> $GITHUB_OUTPUT + fi - id: unzip-changelog - if: ${{ hashFiles('changelog.zip') != '' }} - run: unzip changelog.zip - + name: Unzip changelog artifact + if: ${{ steps.find-changelog.outputs.has-changelog == 'true' }} + env: + ARTIFACT_DIR: ${{ runner.temp }}/artifacts/changelog + run: | + cd "$ARTIFACT_DIR" + unzip changelog.zip + - id: get-deploy-id + name: Get deploy ID + env: + ARTIFACT_DIR: ${{ runner.temp }}/artifacts/docs run: | - deployid=$(> "$GITHUB_OUTPUT" - id: get-deploy-url + name: Get deploy URL env: ORG: ${{ github.event.repository.owner.login }} REPO: ${{ github.event.repository.name }} @@ -86,39 +150,54 @@ jobs: run: | deployurl=$ORG-$REPO-$DEPLOYID.surge.sh echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT - - - uses: actions/setup-node@v4 + + - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6 with: node-version: lts/* - - - name: Deploy docs to surge + + - id: prepare-deploy-dir + name: Prepare deploy directory + shell: bash + env: + DOCS_SRC_DIR: ${{ runner.temp }}/artifacts/docs + DOCS_DEPLOY_DIR: ${{ runner.temp }}/deploy-docs + run: | + mkdir -p "$DOCS_DEPLOY_DIR" + # Copy only the built docs into a clean directory for deployment + cp -R "$DOCS_SRC_DIR"/. "$DOCS_DEPLOY_DIR"/ + + - id: surge-deploy + name: Deploy docs to surge shell: bash env: DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}" - SITE_DIR: ${{ steps.get-top-dir.outputs.top-dir }} + DEPLOY_DIR: ${{ runner.temp }}/deploy-docs run: | npm install -g surge - surge ./$SITE_DIR $DEPLOY_URL --token "$SURGE_TOKEN" + cd "$DEPLOY_DIR" + surge . "$DEPLOY_URL" --token "$SURGE_TOKEN" # If the PR artifacts include a changelog file, add it to the PR as a comment # The changelog contains links to new and changed files in the deployed docs - - name: Comment on PR (changelog) - if: ${{ hashFiles('changelog') != '' }} - uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0 + - id: comment-changelog + name: Prepare changelog comment + if: ${{ steps.find-changelog.outputs.has-changelog == 'true' }} + uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 #v3 with: number: ${{ steps.get-deploy-id.outputs.deploy-id }} recreate: true header: docs-pr-changes - path: changelog + path: ${{ runner.temp }}/artifacts/changelog/changelog GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }} # If there's no changelog, add a generic comment to the PR - - name: Comment on PR (no changelog) - if: ${{ hashFiles('changelog') == '' }} + - id: comment-no-changelog + name: Comment on PR (no changelog) + if: ${{ steps.find-changelog.outputs.has-changelog == 'false' }} env: DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} - uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0 + uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 #v3 with: number: ${{ steps.get-deploy-id.outputs.deploy-id }} header: docs-pr-changes diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml new file mode 100644 index 0000000..c69f266 --- /dev/null +++ b/.github/workflows/docs-generate-html.yml @@ -0,0 +1,97 @@ + +name: "Generate HTML" + +permissions: + contents: read + +# edit the list of branches according to your repository +# the list of branches should contain all the branches in your Antora publish playbooks +on: + push: + branches: + - main + - dev + - '5.x' + - '4.4' + workflow_dispatch: + +# change `dev` and `main` according to your repository's branch names +# `dev` is the branch you use to build and publish to staging +# `main` is the branch you use to build and publish to neo4j.com/docs +# in some cases, PROD_BRANCH and DEV_BRANCH may be the same branch +env: + DEV_BRANCH: 'dev' + PROD_BRANCH: 'main' + +jobs: + + prepare-ref-env: + name: Set build branch and environments + runs-on: ubuntu-latest + outputs: + build-ref: ${{ steps.set-ref-env.outputs.build-ref }} + environments: ${{ steps.set-ref-env.outputs.environments }} + steps: + - name: Set Build Ref + id: set-ref-env + run: | + dev_branch="${{ env.DEV_BRANCH }}" + prod_branch="${{ env.PROD_BRANCH }}" + + if [[ -z "${prod_branch}" ]]; then + build_from="${dev_branch}" + environments='["dev"]' + elif [[ "${GITHUB_REF}" == "refs/heads/${dev_branch}" ]]; then + build_from="${dev_branch}" + environments='["dev"]' + else + build_from="${prod_branch}" + environments='["prod"]' + fi + + if [[ -n "${prod_branch}" && "${dev_branch}" == "${prod_branch}" ]]; then + environments='["dev","prod"]' + fi + + echo "build-ref=${build_from}" >> $GITHUB_OUTPUT + echo "environments=${environments}" >> $GITHUB_OUTPUT + + docs-build: + name: Generate HTML + needs: prepare-ref-env + uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2 + with: + package-script: 'verify:publish' + build-ref: ${{needs.prepare-ref-env.outputs.build-ref}} + fetch-depth: 0 + + docs-verify: + name: Verify HTML + needs: docs-build + uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v2 + with: + failOnWarnings: true + + publish-html: + name: Publish HTML + needs: [docs-verify, prepare-ref-env] + runs-on: ubuntu-latest + + strategy: + matrix: + environments: ${{ fromJson(needs.prepare-ref-env.outputs.environments) }} + + steps: + - name: Publish to ${{ matrix.environments }} + uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 #v4 + with: + token: ${{ secrets.DOCS_DISPATCH_TOKEN }} + repository: neo4j/docs-publish + event-type: publish-html + client-payload: |- + { + "org": "${{ github.repository_owner }}", + "repo": "${{ github.event.repository.name }}", + "run_id": "${{ github.run_id }}", + "publish_env": "${{ matrix.environments }}" + } diff --git a/.github/workflows/docs-pr-checks.yml b/.github/workflows/docs-pr-checks.yml index f4f2f20..7cac105 100644 --- a/.github/workflows/docs-pr-checks.yml +++ b/.github/workflows/docs-pr-checks.yml @@ -1,11 +1,14 @@ - name: "Verify docs PR" +permissions: + contents: read + pull-requests: read + on: pull_request: branches: - - 'main' - - 'dev' + - main + - dev - '5.x' - '4.4' @@ -13,7 +16,7 @@ jobs: # Generate HTML docs-build-pr: - uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v1.2.0 + uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2 with: deploy-id: ${{ github.event.number }} retain-artifacts: 14 @@ -23,7 +26,7 @@ jobs: # By default, the job fails if there are errors, passes if there are warnings only. docs-verify-pr: needs: docs-build-pr - uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v1.2.0 + uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v2 with: failOnWarnings: true @@ -40,14 +43,14 @@ jobs: steps: - name: Get file changes id: get-file-changes - uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32 # v46.0.1 + uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47 with: separator: ',' files_yaml: | pages: - - modules/**/pages/**/*.adoc + - '**/modules/**/pages/**/*.adoc' asciidoc: - - modules/**/*.adoc + - '**/modules/**/*.adoc' # Generate a PR comment if the docs are using the pageList extension # The extension maps asciidoc source files to their HTML output paths @@ -55,7 +58,7 @@ jobs: docs-updates-comment-pr: if: needs.docs-build-pr.outputs.pages-listed == 'success' needs: [docs-build-pr, docs-changes-pr] - uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@v1.2.0 + uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@v2 with: pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }} pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }} diff --git a/.github/workflows/docs-teardown.yml b/.github/workflows/docs-teardown.yml index e21cc3a..d965955 100644 --- a/.github/workflows/docs-teardown.yml +++ b/.github/workflows/docs-teardown.yml @@ -1,11 +1,15 @@ # copy this workflow into your repo name: "Documentation Teardown" +permissions: + contents: read + pull-requests: write + on: pull_request_target: branches: - - 'main' - - 'dev' + - main + - dev - '5.x' - '4.4' types: @@ -16,7 +20,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/setup-node@v4 + - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f #v6 with: node-version: lts/* @@ -39,7 +43,7 @@ jobs: surge teardown $DEPLOY_URL --token "$SURGE_TOKEN" - name: Comment on PR - uses: marocchino/sticky-pull-request-comment@331f8f5b4215f0445d3c07b4967662a32a2d3e31 #v2.9.0 + uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 #v3 with: number: ${{ github.event.pull_request.number }} header: docs-pr-changes @@ -48,4 +52,3 @@ jobs: The preview documentation has now been torn down - reopening this PR will republish it. GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }} - diff --git a/package.json b/package.json index 6ec279e..8053e5a 100644 --- a/package.json +++ b/package.json @@ -4,39 +4,52 @@ "description": "Neo4j HTTP API", "main": "server.js", "scripts": { - "clean": "rm -rf build", "test": "echo \"Error: no test specified\" && exit 1", - "start": "npm update && nodemon -e adoc --exec \"npm run build\" & npm run serve", + "prestart": "npm update", + "start": "nodemon --exec \"npm run build\"", "serve": "node server.js", - "build": "antora --stacktrace preview.yml", - "build-verify": "antora --stacktrace --fetch preview.yml --log-format=json --log-level=info --log-file ./build/log/log.json", - "publish-verify": "antora --stacktrace --fetch publish.yml --log-format=json --log-file ./build/log/log.json" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/neo4j/docs-http-api.git" + "clean": "rm -rf build", + "build": "npm run build:preview", + "postbuild": "node server.js", + "build:preview": "antora preview.yml --stacktrace --log-format=pretty", + "build:publish": "npm run clean && antora publish.yml --stacktrace --log-format=pretty", + "verify:preview": "antora --stacktrace --fetch preview.yml --log-format=json --log-level=info --log-file ./build/log/log.json", + "verify:publish": "antora --stacktrace --fetch publish.yml --log-format=json --log-level=info --log-file ./build/log/log.json" }, - "keywords": [], + "keywords": [ + "antora", + "neo4j" + ], "author": "Neo4j", "license": "ISC", - "bugs": { - "url": "https://github.com/neo4j/docs-http-api/issues" - }, - "homepage": "https://github.com/neo4j/docs-http-api#readme", "dependencies": { - "antora": "^3.1.10", - "@neo4j-antora/aliases-redirects": "^0.2.3", - "@neo4j-antora/antora-add-notes": "^0.3.1", - "@neo4j-antora/antora-page-roles": "^0.3.2", - "@neo4j-antora/antora-table-footnotes": "^0.3.3", - "@neo4j-antora/mark-terms": "1.1.0", + "@neo4j-antora/aliases-redirects": "^0.2.7", + "@neo4j-antora/antora-add-notes": "^0.3.2", + "@neo4j-antora/mark-terms": "^1.1.4", + "@neo4j-antora/roles-labels": "^0.1.8", + "@neo4j-antora/selector-labels": "^0.1.1", + "@neo4j-antora/table-footnotes": "^1.0.1", + "@neo4j-antora/xref-hash-validator": "^0.1.4", "@neo4j-documentation/macros": "^1.0.4", - "@neo4j-documentation/remote-include": "^1.0.0" + "@neo4j-documentation/remote-include": "^1.0.0", + "antora": "3.1.14" }, "devDependencies": { - "express": "^4.21.2", - "nodemon": "^3.1.0" + "express": "5.2.1", + "nodemon": "3.1.14" + }, + "nodemonConfig": { + "watch": [ + "**/modules/**", + "**/antora.yml", + "**/preview.yml", + "**/publish.yml" + ], + "ext": "yml,yaml,adoc,svg,png,jpg", + "ignore": [ + "build/**", + "node_modules/**" + ], + "delay": 1000 } } - - diff --git a/preview.yml b/preview.yml index ab74c0d..a6d129e 100644 --- a/preview.yml +++ b/preview.yml @@ -21,13 +21,18 @@ ui: urls: html_extension_style: indexify +antora: + extensions: + - "@neo4j-antora/aliases-redirects" + - "@neo4j-antora/roles-labels" + - "@neo4j-antora/table-footnotes" + - "@neo4j-antora/xref-hash-validator" + asciidoc: extensions: - "@neo4j-documentation/remote-include" - "@neo4j-documentation/macros" - - "@neo4j-antora/antora-add-notes" - - "@neo4j-antora/antora-page-roles" - - "@neo4j-antora/antora-table-footnotes" + - "@neo4j-antora/mark-terms" attributes: page-theme: docs page-type: Docs diff --git a/publish.yml b/publish.yml index b606879..8d139a0 100644 --- a/publish.yml +++ b/publish.yml @@ -21,13 +21,18 @@ ui: urls: html_extension_style: indexify +antora: + extensions: + - "@neo4j-antora/aliases-redirects" + - "@neo4j-antora/roles-labels" + - "@neo4j-antora/table-footnotes" + - "@neo4j-antora/xref-hash-validator" + asciidoc: extensions: - "@neo4j-documentation/remote-include" - "@neo4j-documentation/macros" - - "@neo4j-antora/antora-add-notes" - - "@neo4j-antora/antora-page-roles" - - "@neo4j-antora/antora-table-footnotes" + - "@neo4j-antora/mark-terms" attributes: page-theme: docs page-type: Docs @@ -43,7 +48,7 @@ asciidoc: includePDF: false nonhtmloutput: "" experimental: '' - copyright: 2025 + copyright: 2026 common-license-page-uri: https://neo4j.com/docs/license/ partials: ROOT:partial$@ # attributes for doc links to other manuals in publish playbook From 319ffa1956dcbbcaf596f98a7dbfc210aebfc120 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 23 Apr 2026 12:12:20 +0200 Subject: [PATCH 15/15] DOCS-395 Update version from 2026.04 to 2026.05 (#163) --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index e271dde..30b0024 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: http-api title: HTTP API -version: '2026.04' +version: '2026.05' start_page: ROOT:index.adoc nav: - modules/ROOT/content-nav.adoc