@neo4j-documentation/macros v1.0.2

= Neo4j Developer Guides & Static Content

image::https://github.com/neo4j-documentation/docs-refresh/workflows/Publish%20Developer/badge.svg[Publish Developer] image::https://api.netlify.com/api/v1/badges/e217b188-6e70-447e-895a-9d8a290b59d2/deploy-status[Netlify Status]

This is an unversioned repo with folders to the different content that will be built with Antora.

Each directory will have a antora.yml file with configuration, then the start_path in antora-playbook.yml will define which subfolder is picked up.

== Installation

In order to build the content,

source,sh npm i

The npm install command will install link:https://docs.antora.org/antora/2.3/cli/[Antora CLI^], which is then used to build the content defined in the Antora Playbooks (*.yml files in the project root).

== Build

To build the content, run the build command:

source,sh npm run build

== Preview

You can run a local server to preview the built content by running:

source,sh npm start

This will launch a server at http://localhost:8000/

== Publishing

Any changes to the master branch will trigger an automatic rebuild of all content using Github Actions. The action runs the npm run build command which builds the following playbooks using the Antora CLI:

• unversioned.yml - Developer guides at neo4j.com/developer/* and Labs pages at neo4j.com/labs/*
• labs-docs.yml - Builds the documentation from remote sources into neo4j.com/labs/{project}/{version}
  • link:https://neo4j.com/labs/neo4j-helm/1.0.0/[Helm^]
  • link:https://neo4j.com/labs/apoc/4.1/[APOC^]
  • link:https://neo4j.com/labs/neosemantics/4.0/[Neosemantics^]
  • link:https://neo4j.com/labs/kafka/4.0/[Neo4j Streams/Kafka^]
  • link:https://neo4j.com/labs/neo4j-helm/1.0.0/[Helm^]
  • link:https://neo4j.com/labs/etl-tool/1.5.0/[ETL Tool^]

The HTML files built by the build command are uploaded to the static-content.neo4j.com S3 Bucket, where it is synced hourly with the link:neo4j.com[] server. The cronjob runs on the hour, every hour so it may take up to an hour for the content to become live.

// === Publishing Content

// To publish an individual section, merge and push your changes to the publish branch of the appropriate repository.

// source,sh // git clone https://github.com/neo4j-documentation/developer-guides // git add . // git commit -m "My changes" // git push origin HEAD:publish

// This will trigger a workflow to rebuild the content and sync the content to the S3 Bucket using link:https://github.com/neo4j-documentation/developer-guides/actions[Github Actions^].

== Theme Specifics

For more information on specific theme features, clone the link:https://github.com/neo4j-documentation/documentation-starter[Documentation Starter] and run npm start.

== Migrating from the old Developer Guides

=== Variables, Attributes, etc

Instead of defining variables in a text file (think versions.txt), these are now defined under asciidoc and attributes in either the playbook (eg developer.yml) or inside antora.yml in the content repo.

.developer.yml playbook

source,yaml

asciidoc: attributes: page-theme: developer

page-cdn: /static/assets

.antora.yml in content repo

source,yaml

asciidoc: attributes: img: https://dist.neo4j.com/wp-content/uploads/ theme: developer neo4j-ogm-version: 3.1.6 spring-data-neo4j-version: 5.1.3.RELEASE neo4j-stable-version: 4.0.3 bolt-driver-version: 1.7.0

java-driver-version: 4.0.1

=== Page Level

source,adoc

:level: Beginner role=expertise

{level}

Becomes:

source,adoc

:level: Beginner role=expertise {level}

{level}

=== Renamed Attributes

%header,cols=2* |=== | Old Name | New Name

| slug | Not required | icons | Not required | section | Not required | section-link | Not required | setanchors | Not required | toc | Not required | toc-title | Not required | setanchors | Not required | toclevels | Not required | toc-placement | Not required | northwind | Not required | level | Create an additional attribute called :page-level: |===

// == Content

// === Developer // // /developer <- developer home page // /developer/get-started <- structured content // /developer/get-started/rdbms-vs-graph // /developer/get-started/nosql-vs-graph // /developer/get-started/nosql-vs-graph // /developer/platform // /developer/platform/neo4j-browser // /developer/platform/neo4j-bloom // /developer/platform/neo4j-desktop // /developer/platform/graph-apps <- (or neo4j-desktop/graph-apps) // /developer/cypher // /developer/cypher/filtering // /developer/cypher/subqueries // /developer/cypher/user-defined-functions // /developer/modeling // /developer/modeling/worked-example // /developer/drivers/ // /developer/drivers/java // /developer/drivers/javascript // /developer/drivers/dotnet //

// === Labs // // /labs <- Labs homepage with list of all projects // /labs/apoc <- About page for APOC // /labs/apoc/quick-start <- Quick start "guide" // /labs/apoc/docs <- Hard core Manuals/"reference" // /labs/apoc/docs/3.5 // /labs/apoc/docs/4.0 // /labs/neosemantics <- About page for Neosemantics // /labs/neosemantics/quick-start <- Quick start "guide" // /labs/neosemantics/docs <- Hard core Manuals/"reference" // /labs/neosemantics/docs/3.5 // /labs/neosemantics/docs/4.0 //

// === Migration

// ` // :level: Beginner // role=expertise // {level}

// becomes

// :page-level: Beginner // `