Create a private repository based on the example template repository, or set up the GitHub action in any repository using the instructions below.
Write normal Markdown, with a YAML document metadata block at the top, containing the relevant metadata.
---
title: "Document Title"
version: 0.1
revision: 1
date: 2022/09/17
type: SPECIFICATION
status: DRAFT
...
status can be any string, but if it is DRAFT then the tool will render a watermark on the PDF.
status: DRAFT
You can specify either the bluetop or greentop (default) cover backgrounds with the following optional YAML metadata field:
template: bluetop
or
template: greentop
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:
---
\tableofcontents
\listoffigures
\listoftables
---
Tables in Markdown look like the following:
| **Revision** | **Date** | **Description** |
| ------------ | ---------- | --------------- |
| 0.1/1 | 2022/09/17 | Initial draft |
| 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:
> Informative text goes here!
>
> It can be multiple paragraphs, if you wish.It will look like this in the GitHub markdown view:
Informative text goes here!
It can be multiple paragraphs, if you wish.
The tool will insert the "Start of informative text" / "End of informative text" delimiters into the informative text blocks automatically.
You can include diagrams using Mermaid syntax:
```mermaid {caption="Sequence Diagram A"}
sequenceDiagram
Host->>TPM: TPM2_Startup
loop Measurements
Host->>TPM: TPM2_PCR_Extend
end
Host->>TPM: TPM2_Quote
TPM->>Host: <quoted PCRs>
```The code above generates a diagram that looks like this:
sequenceDiagram
Host->>TPM: TPM2_Startup
loop Measurements
Host->>TPM: TPM2_PCR_Extend
end
Host->>TPM: TPM2_Quote
TPM->>Host: <quoted PCRs>
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:
```mermaid
Mermaid supports the following types of diagrams:
- Sequence diagrams (as above)
- Flow charts
- Gantt charts
- UML class diagrams
- Git branch graphs
- And more
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.
produces:
In the example above, "Image B" is the name shown in the figure caption and table of figures.
To exclude the caption and table-of-figures entry, leave the caption blank (i.e., )
See the samples in the root 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
on:
push:
branches:
- main
pull_request:
workflow_dispatch:
jobs:
render:
runs-on: ubuntu-latest
container:
image: ghcr.io/trustedcomputinggroup/pandoc:0.3.0
name: Render PDF
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Render
uses: trustedcomputinggroup/[email protected]
with:
input-md: main.md
output-pdf: spec.pdf
- name: Upload samples
uses: actions/upload-artifact@master
with:
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: spec.pdf
if: github.event_name != 'pull_request'Either clone the repository and install Pandoc and its dependencies, or
docker pull ghcr.io/trustedcomputinggroup/markdown:latestWhen running Pandoc (either directly or using docker run), you'll have to pass all the arguments that the action does.
Send a PR! A GitHub Action in this repo will automatically run the tools with all your changes on top. You can find the rendered samples under "action validation" in the "checks" tab of your PR:
