The showyourwork workflow is intended to help authors publish the code that generated the figures and results in a scientific article. It ensures that the compiled article PDF is always in sync with all of the code used to generate it. It does this automatically—and seamlessly—with the help of the Snakemake workflow management system, the tectonic typesetting engine, and Github Actions CI.

Within the showyourwork workflow, scientific articles exist as GitHub repositories with a specific layout. Whenever new commits are pushed to the remote repository, a GitHub action is triggered that automatically builds the article from the input figure scripts, manuscript files, and conda environment file, following the instructions specified in the Snakefile.

The article PDF (along with a tarball containing all of the output) is then pushed to a special branch (usually main-pdf) on the repository. This article is decorated with badges linking to the exact versions of the files on GitHub used to generate it.

Thanks to the magic of Snakemake, showyourwork is both lightweight—it should work out-of-the-box for most users—and highly customizable. It also uses intelligent caching to never re-run things it doesn’t have to (like figure scripts that haven’t changed), even when running on the cloud.

To get started with showyourwork, check out the quickstart tutorial. The full documentation is available here.