Contributing to documentation¶

The Testcontainers for Go documentation is a static site built with MkDocs. We use the Material for MkDocs theme, which offers a number of useful extensions to MkDocs.

We publish our documentation using Netlify.

Adding code snippets¶

To include code snippets in the documentation, we use the codeinclude plugin, which uses the following syntax:

[Human readable title for snippet](./relative_path_to_example_code.go) targeting_expression
[Human readable title for snippet](./relative_path_to_example_code.go) targeting_expression

Where each title snippet in the same codeinclude block would represent a new tab in the snippet, and each targeting_expression would be:

block:someString or
inside_block:someString

Please refer to the codeinclude plugin documentation for more information.

Previewing rendered content¶

Using Python locally¶

From the root directory of the repository, you can use the following command to build and serve the documentation locally:

make serve-docs

It will use a Python's virtual environment to install the required dependencies and start a local server at http://localhost:8000.

Once finished, you can destroy the virtual environment with the following command:

make clean-docs

PR Preview deployments¶

Note that documentation for pull requests will automatically be published by Netlify as 'deploy previews'. These deployment previews can be accessed via the deploy/netlify check that appears for each pull request.