GraphAcademy Course Content

This repository holds the course curriculum for GraphAcademy.

Prerequisites

You will need the following software to run GraphAcademy locally:

• Docker

• AWS CLI

• Node.js

• Git

Recommended:

• VS Code

• Asciidoc extension

Setup

This repository uses docker-compose to create a local server using the latest production build of the GraphAcademy website (repo here). The docker image is stored on AWS ECR, so you will need credentials - talk to Adam.

1. Clone this repository

2. Install the AWS CLI

3. Run aws configure to configure the AWS CLI

4. Log in to docker using the credentials above:

   aws ecr get-login-password --region us-east-1 | docker login -u AWS --password-stdin 715633473519.dkr.ecr.us-east-1.amazonaws.com

5. Install the dependencies using NPM

   npm install

6. You will need to create a .env file in the project root with Auth0 configuration. You can get an example file from Adam or Martin.

   • NEO4J_HOST

   • NEO4J_USERNAME

   • NEO4J_PASSWORD

   • AUTH0_CLIENT_ID

   • AUTH0_CLIENT_SECRET

   • AUTH0_ISSUER_BASE_URL

   • CDN_URL

7. Run npm run dev to start the server

   • The local server will be available at http://localhost:3000
     

   • A Neo4j instance will be available on http://localhost:7474
     

   • A process will listen for changes in the asciidoc/ folder and sync the content to Neo4j

Devcontainer

If you are using VS Code, you can use the devcontainer to run the application in a container.

You will need the Dev Containers extension installed and Docker running.

When the devcontainer is started, it will:

• Install all dependencies

• Start the GraphAcademy application and Neo4j database.

You can run the content update and sync by running the following command in a terminal:

npm run dev:watch

File Structure

All content lives in the asciidoc/ directory. As you modify the content, a process will sync the course structure to Neo4j.

• categories/ - Category information

• courses/ - All courses are organised into the own folder structure with modules and lessons

• emails/ - The emails sent to users on enrolment, completion and a reminder email when the user has been inactive for 7 days

• languages/ - i18n phrases for courses in languages other than English.

• pages/ - "CMS" content displayed throughout the website, for example the /certifications/ page

• shared/ - Content shared across courses

• statuses/ - Meta data around course statuses

Course Structure

asciidoc
 + courses/
    + {course-slug}/                  - Course Folder
       + badge.svg                    - SVG badge used across the site
       | overview.adoc                - Course meta data and content used on the course overview page
       + modules/                     - Each course is split into modules
         + {module-slug}/
           | overview.adoc
           + lessons/                 - A module is split into lessons
             + {lesson-slug}/
               | lesson.adoc
               + questions/           - A lesson can be optional, otherwise will have questions.
                 | question-1.adoc
                 | question-2.adoc

Workshops

Workshops are instructor-led courses that are designed to be delivered in a classroom setting. They should not be used for self-study. The following workshops are available:

• Introduction to Graph Databases Workshop (workshop-fundamentals) - Learn about Graph theory, Neo4j fundamentals, and how to read and write data using Cypher.
  View Workshop

• Importing Data into Neo4j Workshop (workshop-importing) - Learn how to import your data into Neo4j
  View Workshop

• Gen-AI - Hands-on Workshop (genai-workshop) - GenAI Beyond Chat with RAG, Knowledge Graphs and Python
  View Workshop

• Mastering Retrieval-Augmented Generation (RAG) (genai-workshop-graphrag) - Learn how to implement GraphRAG with the neo4j-graphrag Python Package
  View Workshop

QA

A suite of tests have been setup to ensure courses meet the right standard.

To open the test suite run:

npm run test

This will open up a UI. Select E2E testing > Chrome and then select the course.

To create a test for your course, you can copy one of the existing files in the cypress/e2e folder to cypress/e2e/{slug}.cy.js and then change line 6 to cy.getCourseDetails('{slug}')/

You can run QA tests for all courses by running:

npm run test:qa

You can run QA tests for specific courses by setting the COURSES environment variable:

COURSES=fundamentals,aura npm run test:qa

Skipping Tests

You can skip certain time-consuming tests by setting environment variables:

• SKIP_LINK_CHECKS=true - Skip validation of external links (GitHub repositories, lesson links)

• SKIP_CYPHER_CHECKS=true - Skip Cypher query validation (file existence checks still run)

Cursor QA checks

You can use Cursor to run automated QA checks on the course content.

Cursor prompts are stored in the .cursor/ folder.

To run the checks against a specific course , use the following commands:

@review-lesson-content.mdc for @genai-graphrag-python
run and fix COURSES=graphrag-python npm run test qa
@technical-lesson-review.mdc
@review-course.mdc

Fact checking

Use Adam’s neo4jdocs-mcp mcp server to fact check the course content.

First, clone the repo:

git clone [email protected]:neo4j-documentation/neo4j-docs-mcp.git

Install the dependencies:

cd neo4j-docs-mcp/mcp-neo4j-docs
uv install

Then, add the mcp server to Cursor:

mcp.json

{
  "mcpServers": {
    "neo4j-docs": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/neo4j-docs-mcp/mcp-neo4j-docs",
        "run",
        "main.py"
      ]
    }
  }
}

Then run the cursor prompt:

@fact-check-lessons.mdc for @genai-graphrag-python

Contributing

To create a new course or modify an existing course, please create a new branch and make your changes. Once you have finished, create a new PR and add adam-cowley as a reviewer.

git checkout -b new-course
mkdir asciidoc/courses/new-course/
echo "= New Course\n:status: draft" > asciidoc/courses/new-course/course.adoc

git add asciidoc/courses/new-course/
git commit -m "Added new course"
git push --set-upstream origin new-course

Before creating the PR, please rebase your branch on the main branch.

git fetch origin main
git rebase main

Creating a PR

When you create a PR, select the correct template:

• Course Draft Template

• Course Release Template

The checklist must be completed before the PR can be merged.

Generating a Banner

To generate a banner image for a course, run the following command:

npm run generate:ogimages

The command scans through the asciidoc/ folder, finds all courses that don’t include a banner.png image and attempts to create them.

Deploying Changes

When a new application server is created, the latest tagged version of this repository is downloaded by the server.

You can use the npm version command to create a new tag. First, run a git pull --tags to get the latest commits and tags from the server, then run the npm version command to create a new tag. Once you are done, run git push --tags.

git pull --tags origin main
npm version patch
git push --tags origin main

• npm version patch - To be used when minor fixes are made to an existing course

• npm version minor - To be used when a new course is released

• npm version major - To be used when a major change is made to the repository - for example, multiple course changes, or addition of a new category

Linking Certifications

To link certifications from the certifications repository, create a symlink:

ln -s ../certifications/asciidoc/certifications/neo4j-certification asciidoc/certifications/neo4j-certification

Documentation

Additional documentation is located in the Docs folder.