How we teach ›Lesson Types
Challenge Lessons

How we teach

Introduction to GraphAcademy’s Learning Philosophy

Developing a GraphAcademy course

Lesson Types

Releasing courses

Monitoring courses

Challenge Lessons

Challenge lessons provide hands-on exercises where learners apply what they’ve learned. They typically involve coding, configuration, or problem-solving tasks.

Configuration

Example from cypher-fundamentals course:

= Retrieving Nodes
:order: 2
:type: challenge
:sandbox: true

Now for a challenge, use what you have learnt to answer the following question.

:leveloffset: +1

[.question]
= When was Kevin Bacon born?

Complete the Cypher query to find the year that [copy]#Kevin Bacon# was born.
This value is stored in the [copy]#born# property.

Replace the `?????` with the correct Cypher to find the year `Kevin Bacon` was `born`.

[source, cypher]

MATCH (p:Person {name: "?????"}) RETURN p.?????

Select the correct year:

* [ ] 1954
* [x] 1958
* [ ] 1962
* [ ] 1966

[TIP,role=hint]
.Hint
====
You need to filter the `(:Person)` node with the name property of `Kevin Bacon`. The property you are looking for is the `born` property of the `(:Person)` node.
====


[TIP,role=solution]
.Solution
====
To find the answer, run the following query:

[source,cypher]

MATCH (p:Person {name: "Kevin Bacon"}) RETURN p.born

This query will return `1958`, the `born` property of the `(:Person)` node with the `name` property of `Kevin Bacon`.
====

:leveloffset!:

[.summary]
== Summary

In this challenge, you demonstrated your skills to retrieve and filter nodes.

In the next lesson, you will learn how to traverse patterns in the graph with your queries.

Required Attributes

  • :type: challenge - Identifies this as a challenge lesson

  • :order: - Numeric order within the module

  • Title - Level 1 heading describing the challenge

Common Attributes

  • :lab: - Link to sandbox or development environment (e.g., {repository-blob}/{branch}/src/main/java/App.java)

  • :branch: - Git branch containing the challenge code (e.g., 01-connect-to-neo4j)

  • :optional: true - Makes the challenge optional

  • :sandbox: true - Provides a Neo4j sandbox instance for the challenge

  • :test-filename: - Name of the test file to run for verification

  • :test-method: - Specific test method to verify completion

Completion

Challenges use questions::[] to verify completion. The question typically checks that the learner has completed the task correctly.

Unlike standard lessons, challenges don’t use read:: directives.

Open in Codespaces

Challenge lessons typically require a development environment. Use GitHub Codespaces to provide learners with a pre-configured environment.

Course Setup:

In your course.adoc, define the repository:

:repository: neo4j-graphacademy/drivers-java

This automatically creates attributes:

  • {repository-link} - Link to the repository

  • {repository-raw} - Raw file URL

  • {repository-blob} - Blob file URL

Setup Lesson:

Create a setup lesson that includes the Codespaces link:

= Setup
:type: lesson
:order: 1
:branch: main

== Get started

The repository, link:{repository-link}[{repository}^], has been created for this course.
It contains any starter code and resources you need.

You can use a link:https://github.com/codespaces[GitHub codespace^] as an online IDE and workspace for this course.
It will automatically clone the course repository and set up your environment.

link:https://github.com/codespaces/new/{repository}[Open in GitHub Codespace^,role="btn"]

[IMPORTANT]
.GitHub Codespaces
====
You will need to login with a GitHub account.
The link:https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts[GitHub Codespaces free monthly usage^] will cover the duration of this course.
====

The shared file creates a button:

link:https://github.com/codespaces/new/{repository}[Open in GitHub Codespace^,role="btn"]

Challenge Lessons:

Use the :branch: attribute to link to specific solution branches:

= Add the Driver
:type: challenge
:branch: 01-connect-to-neo4j

Your challenge is to modify the code...

[source,java]

Unresolved directive in lesson.adoc - include::{repository-raw}/{branch}/src/main/java/App.java[tag=driver]

The {repository-raw}/{branch} combination links to the solution code on that branch.

Example from drivers-java course:

  • Setup lesson (lesson 0) - Opens Codespaces on main branch

  • Challenge lessons - Reference specific solution branches (01-connect-to-neo4j, 02-execute-query, etc.)

  • Each challenge includes code snippets from its solution branch using include::{repository-raw}/{branch}/…​

Best Practices

  • Provide clear, numbered instructions

  • Break complex challenges into smaller steps

  • Include examples when introducing new concepts

  • Offer hints or links to relevant documentation

  • Ensure verification is fair and matches instructions

  • Use :branch: to reference solution code without spoiling the challenge

  • Link to specific files using :lab: {repository-blob}/{branch}/path/to/file

  • Celebrate success in the summary

Summary

In this lesson, you learned about challenge lessons, which provide hands-on exercises for learners to apply their knowledge.

Challenge lessons require :type: challenge, an :order:, instructions, and questions::[] for verification.

You also learned how to use GitHub Codespaces to provide pre-configured development environments, and how to use the :branch: attribute to reference solution code across different branches.

Chatbot

How can I help you today?