This directory represents the eventual home for all code examples across MongoDB documentation properties.

Details TBD as infrastructure is added and projects related to standardization and coverage are completed.

Each programming language has its own directory, with each driver or product as a subdirectory. Each directory is split into examples and tests. Examples live in stand-alone files in the language/driver/examples directory, grouped by topic. Tests live in consolidated files in the language/driver/tests directory, with each test executing example code to verify that:

• Examples compile and run
• Examples do what we say they do

We use tooling to extract the tested code examples to the content/code-examples/tested directory. The content of the content/code-examples/tested directory is tested, snipped code that is ready to use in the documentation.

Because these examples are designed to be runnable and testable, they contain additional code related to our infrastructure that is not relevant to the developer consuming our documentation. For example, the tests use language-idiomatic methods for reading environment values to get the appropriate connection string, or have method signatures or function calls with return values for testing purposes that are not needed in the docs example.

Docs uses a markup tool called Bluehawk to add markup to extract only the relevant parts of the code examples. Each language directory includes a script, snip.js, that uses this markup tool to extract relevant code to the content/code-examples/tested directory. For more details, refer to the language-specific README.md on generating code examples.

For docs purposes, writers should only use code examples from the content/code-examples/tested directory. Using an example directly from the language/driver/examples directory may contain code that is not desired in the docs.

When any file in any of the language/driver/examples directories are updated in a PR, the GitHub workflows contained in the .github/workflows directory automatically run the test suite. These workflows report the results of the test suite runs as passes or failures on the PR.

If changing an example causes its test to fail, this should be considered blocking for merging the example. The PR should not be merged until the example and/or test is fixed and the test passes.

If changing an example causes an unrelated test to fail, create a Jira ticket in the DOCSP project with the component DevDocs. Provide a link to your PR and details about the test failure. This should not block merging an example update.

Each language directory contains a README.md with instructions about how to run the tests locally. Contributors can and should run tests for any examples they're changing locally during the update process. Reviewers don't need to run the tests directly, since the tests run automatically in CI, but if they want to run the tests, they can check out the PR and run the tests locally.

A language-agnostic comparison engine lives in tools/comparison-kernel/. It is shipped as native per-OS Go binaries committed under tools/comparison-kernel/bin/ and invoked by each language suite through a thin bridge that talks newline-delimited JSON over the binary's stdin/stdout. No external runtime is required. Centralising the comparison logic keeps ellipsis handling, Extended JSON normalisation, and schema validation consistent across suites.

Integration status:

Mongosh examples are shell scripts executed as mongosh --file subprocesses, so the "actual" value a test receives is raw stdout text rather than a JSON-serialisable structure like the drivers produce. That stdout uses shell-specific syntax — ObjectId(...), ISODate(...), bare object keys, multiple top-level documents with no array wrapper, and assorted REPL artifacts — which the kernel's JSON-shaped input contract can't accept directly.

The mongosh suite parses that output in-process with Node's vm module against the mongodb package's BSON type constructors (see MongoshOutputParser.js) before comparing. Routing through the kernel would require porting that parser into Go and duplicating the BSON type wiring, with no behavioural gain over the driver suites that already feed the kernel structured data. Until that trade-off changes, mongosh keeps its own comparison engine.

Our build toolchain can't use files outside of a project/version/source directory. To avoid copying code examples into every docs project source directory, we use symlinks. Creating a symlink in a docs project makes the examples in content/code-examples/tested available to that project.

Each docs project directory and version must have a symlink if you want to use the tested code examples.

In the terminal, make sure you are in the directory you want to make a symlink in. For example, run cd content/manual/manual/source/code-examples. Then, use the following command to see all the files in the directory.

ls -l

In the outputted list, see if there is a name with this structure: tested -> ../../../../code-examples/tested. If it exists, a symlink to the tested code examples has already been created.

You can also specify the symlink you are checking for by adding its name to the previous command:

ls -l tested

You can see the actual path that the symlink routes to by using this command:

realpath tested

If the result matches ../docs-mongodb-internal/content/code-examples/tested, then the symlink has already been properly created.

If there is no symlink created, then use this command inside the correct /source/code-examples directory to create one:

ln -s ../../../../code-examples/tested

💡 Tip: The nesting level may vary depending on whether the docs project is versioned. Add or omit ../ as necessary to create the symlink to the correct directory. Example: if creating a symlink in manual/manual/source/code-examples, there should be 4 nesting levels -> ../../../../code-examples/tested.

Make sure to check that it has been properly created using the steps outlined in Checking if a directory has a symlink.

To use the code examples on a page, use the ..literalinclude:: directive with the following file path structure:

/code-examples/tested/language/driver/topic/subtopic/snippetname

For example, to access the snippet generated from tutorial_app.py, use this file path:

.. literalincude:: /code-examples/tested/python/pymongo/aggregation/pipelines/filter_tutorial.snippet.sort.py
   :language: python
   :copyable: true
   :category: usage example
   :dedent: