Write normal Markdown, with a YAML front matter with the relevant metadata. See the[sample](sample) directory for some examples.

Create a private repository based on the

[example template repository](https://github.com/TrustedComputingGroup/specification-example),

or set up the GitHub action in any repository using the[instructions below](#setting-up-the-github-action).

Write normal Markdown, with a YAML document metadata block at the top, containing the relevant metadata.

`status` can be any string, but if it is`DRAFT` then the tool will render a watermark on the PDF.

You can specify either the`bluetop` or`greentop` (default) cover backgrounds with the following optional YAML metadata field:

or

Horizontal separators are transformed by the workflow into page breaks for readability in both GitHub and PDF views.

Provide a table of contents, list of figures, and list of tables anywhere

(usually, after the disclaimers, change history, and document-style remarks)

in the document with:

Tables in Markdown look like the following:

|**Revision**|**Date**|**Description**|

| ------------| ----------| ---------------|

| 0.1/1| 2022/09/17| Initial draft|

TCG makes use of a gray box for "informative text." To write informative text in your Markdown source, use the block-quote syntax:

> It can be multiple paragraphs, if you wish.

It will look like this in the GitHub markdown view:

The tool will insert the "Start of informative text" / "End of informative text" delimiters to the informative text blocks automatically.

You can include diagrams using[Mermaid](https://mermaid-js.github.io/mermaid/#/) syntax:

If a list of figures is included (`lof: true` in the YAML preamble) then there will be a link to a figure called "Sequence Diagram A".

In the example above, "Sequence Diagram A" is the name shown in the figure caption and table of figures.

To exclude the caption and table-of-figures entry, leave out the caption on the first line, i.e. just:

You can also include images. Note: GitHub and Pandoc disagree somewhat on the paths to images,

so the safest path to success is to keep the Markdown source and image files all

together in the**root** of the repository.

Mermaid supports the following types of diagrams:

* Sequence diagrams (as above)

* Flow charts

* Gantt charts

* UML class diagrams

* Git branch graphs

* And[more](https://mermaid-js.github.io/mermaid/#/)

You can also include images if you check them into the root of the repository.

Note: GitHub and Pandoc disagree somewhat on the paths to images,

so the safest path to success is to keep the Markdown source and image files

all together in the**root** of the repository.



If a list of figuresisincluded (`lof: true` in theYAML preamble) then there will be a link to a figure called "Image B".

In the example above, "Image B"isthe name shown in thefigure caption and table of figures.

See the[sample](sample) directory for more examples.

Here is an example of a GitHub Action configuration that renders a Markdown file to PDF, attaches it to the workflow, and checks it into the repo (if not a pull request):

name:Render

render:

runs-on:ubuntu-latest

container:

image:ghcr.io/trustedcomputinggroup/pandoc:latest

permissions:

contents:read

name:Render the example text

image:ghcr.io/trustedcomputinggroup/pandoc:0.3.0

name:Render PDF

steps:

-name:Checkout

uses:actions/checkout@v3

-name:Render

uses:trustedcomputinggroup/markdown@latest

uses:trustedcomputinggroup/markdown@v0.2.5

with:

input-md:lorem.md

output-pdf:lorem.pdf

input-md:main.md

output-pdf:spec.pdf

-name:UploadArtifact

-name:Uploadsamples

uses:actions/upload-artifact@master

with:

name:lorem.pdf

path:lorem.pdf

name:spec.pdf

path:spec.pdf

-name:Check in latest render

uses:stefanzweifel/git-auto-commit-action@v4

with:

commit_message:Generate latest PDF

file_pattern:lorem.pdf

file_pattern:spec.pdf

if:github.event_name != 'pull_request'