Caltech Library logo

Codemeta + Pandoc Examples

In this repository you see three examples of using Pandoc, Pandoc templates and codemeta.json to create an about page, a CITATION.cff and an file.

Generating a CITATION.cff

The codemeta.json file can be use to generate a CITATION.cff file using the Pandoc template codemeta-cff.tmpl.

    echo '' | pandoc -s --metadata title='Citation' \
                        --metadata-file codemeta.json \
                        --template codemeta-cff.tmpl \

Generating an about page

Like CITATION.cff we can generate a standard about page, from our codemeta.json using the Pandoc template codemeta-about.tmpl.

    echo '' | pandoc -s --metadata title='About' \
                        --metadata-file codemeta.json \
                        --template codemeta-about.tmpl \

Generating version.sql

If you’re building a Postgres+PostgREST application it is nice to have an end point the shows the name and version of the web application you are building. This can be done with the codemeta-version-sql.tmpl Pandoc template.

    echo '' | pandoc -s metadata title='Version Info' \
                     --metadata-file codemeta.json \
                     --template codemete-version-sql.tmpl \

Generating an

The nice thing about the Pandoc approach is you can also use it as a shell script generator. Today (2023) many software tools[1] developers use have installation instructions like

    curl | sh

With a single POSIX shell installer script you easily install your tools on macOS and Linux.

The codemeta.json file provides much of what is needed to generate the installer script from codemeta-installer.tmpl. There are three addition Pandoc metadata variables needed not explicitly found in the codemeta.json. The installer script expects to use a Zip file as an q0Additionally you need to name the zip archive of the content to be installed needs to be predictably named.

To have Pandoc generate a workable installer script requires to parts. First the name of your installation zip files need to be predictable.

Secondly the codemeta-installer.tmpl file needs to know some metadata inorder for the generated script to be runable.

The [codemeta.json] file provides much of the information needed to render our Our template, does make some specific assumptions

This would be the name of your Git repository, e.g. datatools
This would be the version number without the leading “v”, e.g. “0.0.1”
would be “macOS”, “Linux” or “Windows”
This would be what is reported by the command uname -m

Rendering the file can be done with the following Pandoc command.

echo '' | pandoc -s --metadata title='Installer' \
            --metadata-file codemeta.json \

If you host this installer script can then be uploaded to your website. The curl command would be of the form

    curl <URL_TO_SITE>/ | sh

[1]: Examples Rust with Rustup and Haskell’s GHCup