diff --git a/.github/workflows/docs-branch-checks.yml b/.github/workflows/docs-branch-checks.yml deleted file mode 100644 index caa09013d..000000000 --- a/.github/workflows/docs-branch-checks.yml +++ /dev/null @@ -1,52 +0,0 @@ -# This is an example of the docs-pr.yml workflow available from the recrwplay org -name: "Verify Branch" - -on: - # push: - # branches: - # - dev - # schedule: - # - cron: '00 16 * * *' - workflow_dispatch: - inputs: - html: - description: 'Generate HTML' - type: boolean - required: false - default: true - links: - description: 'Check links' - type: boolean - required: false - default: true - lint: - description: 'Lint docs' - type: boolean - required: false - default: false - -jobs: - - docs-build: - if: ${{ inputs.html || github.event_name == 'push' }} - name: Generate HTML - uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v1.2.0 - with: - retain-artifacts: 14 - deploy-id: 0 - - docs-verify: - name: Verify HTML - needs: docs-build - uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v1.2.0 - - docs-links: - if: ${{ inputs.links || github.event_name == 'push' }} - name: Check links - needs: docs-build - uses: neo4j/docs-tools/.github/workflows/reusable-docs-links.yml@v1.2.0 - - docs-lint: - if: ${{ inputs.lint || github.event_name == 'push' }} - name: Lint docs - uses: neo4j/docs-tools/.github/workflows/reusable-docs-lint.yml@v1.2.0 diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml new file mode 100644 index 000000000..0474567e0 --- /dev/null +++ b/.github/workflows/docs-generate-html.yml @@ -0,0 +1,88 @@ + +name: "Generate HTML" + +# 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: + - 'dev' + - 'main' + - '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: + PROD_BRANCH: 'main' + DEV_BRANCH: 'dev' + +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: | + if [[ "${GITHUB_REF}" == "refs/heads/${{ env.DEV_BRANCH }}" ]]; then + build_from=${{ env.DEV_BRANCH }} + environments='["dev"]' + else + build_from=${{ env.PROD_BRANCH }} + environments='["prod"]' + fi + # if dev branch = prod branch publish to both + if [[ "${{ env.DEV_BRANCH }}" == "${{ env.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@bf47d102fdb849e755b0b0023ea3e81a44b6f570 # v2.1.2 + 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 }}", + "args": "--dryrun", + "publish_env": "${{ matrix.environments }}" + } diff --git a/.github/workflows/docs-pr-checks.yml b/.github/workflows/docs-pr-checks.yml index a98780604..5ed5c4365 100644 --- a/.github/workflows/docs-pr-checks.yml +++ b/.github/workflows/docs-pr-checks.yml @@ -13,17 +13,16 @@ 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 # Parse the json log output from the HTML build, and output warnings and errors as annotations # Optionally, fail the build if there are warnings or errors # 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 @@ -55,7 +54,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 }} + pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }} \ No newline at end of file diff --git a/package.json b/package.json index d9a2ec354..5c899acea 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,20 @@ { - "name": "docs-template", + "name": "docs-operations", "version": "1.0.0", - "description": "Template repo for Neo4j documentation projects", + "description": "Neo4j Operations documentation", "main": "server.js", "scripts": { "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", - "adoc-gen": "node scripts/adoc-gen.js", - "build": "antora preview.yml --stacktrace --log-format=pretty", - "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" + "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": [ "antora", @@ -19,23 +23,31 @@ "author": "Neo4j", "license": "ISC", "dependencies": { - "@antora/cli": "^3.1.7", - "@antora/site-generator-default": "^3.1.7", - "@neo4j-antora/antora-add-notes": "^0.3.1", - "@neo4j-antora/antora-modify-sitemaps": "^0.4.4", + "antora": "3.1.14", + "@neo4j-antora/antora-add-notes": "^0.3.2", "@neo4j-antora/antora-page-roles": "^0.3.2", - "@neo4j-antora/antora-table-footnotes": "^0.3.2", "@neo4j-antora/antora-unlisted-pages": "^0.1.0", - "@neo4j-documentation/macros": "^1.0.2", + "@neo4j-antora/roles-labels": "^0.1.1", + "@neo4j-antora/table-footnotes": "^1.0.0", + "@neo4j-antora/xref-hash-validator": "^0.1.3", + "@neo4j-documentation/macros": "^1.0.4", "@neo4j-documentation/remote-include": "^1.0.0" }, "devDependencies": { "express": "^4.19.2", "nodemon": "^3.1.0" }, - "overrides": { - "@antora/site-generator-default": { - "glob-parent": "6.0.2" - } + "nodemonConfig": { + "watch": [ + "**/modules/**", + "**/antora.yml", + "**/preview.yml", + "**/publish.yml" + ], + "ext": "yml,yaml,adoc,svg,png,jpg", + "ignore": [ + "build", + "node_modules" + ] } } diff --git a/preview.yml b/preview.yml index 5941a1e47..f88c4f49b 100644 --- a/preview.yml +++ b/preview.yml @@ -24,11 +24,10 @@ urls: antora: extensions: - - require: "@neo4j-antora/antora-modify-sitemaps" - sitemap_version: '5' - sitemap_loc_version: 'current' - move_sitemaps_to_components: true - - require: "@neo4j-antora/antora-unlisted-pages" + - "@neo4j-antora/antora-unlisted-pages" + - "@neo4j-antora/roles-labels" + - "@neo4j-antora/table-footnotes" + - "@neo4j-antora/xref-hash-validator" asciidoc: extensions: @@ -36,7 +35,6 @@ asciidoc: - "@neo4j-documentation/macros" - "@neo4j-antora/antora-add-notes" - "@neo4j-antora/antora-page-roles" - - "@neo4j-antora/antora-table-footnotes" attributes: page-theme: docs page-type: Docs @@ -51,7 +49,7 @@ asciidoc: includePDF: false nonhtmloutput: "" experimental: '' - copyright: '2024' + copyright: '2025' common-license-page-uri: https://neo4j.com/docs/license/ check-mark: icon:check[] cross-mark: icon:times[] diff --git a/publish.yml b/publish.yml index dca563bdd..db079e03b 100644 --- a/publish.yml +++ b/publish.yml @@ -25,7 +25,10 @@ urls: antora: extensions: - - require: "@neo4j-antora/antora-unlisted-pages" + - "@neo4j-antora/antora-unlisted-pages" + - "@neo4j-antora/roles-labels" + - "@neo4j-antora/table-footnotes" + - "@neo4j-antora/xref-hash-validator" asciidoc: extensions: @@ -33,7 +36,6 @@ asciidoc: - "@neo4j-documentation/macros" - "@neo4j-antora/antora-add-notes" - "@neo4j-antora/antora-page-roles" - - "@neo4j-antora/antora-table-footnotes" attributes: page-theme: docs page-type: Docs @@ -48,7 +50,7 @@ asciidoc: includePDF: false nonhtmloutput: "" experimental: '' - copyright: '2024' + copyright: '2025' common-license-page-uri: https://neo4j.com/docs/license/ check-mark: icon:check[] cross-mark: icon:times[]