Initial check-in of GitHub Action

This is an initial stab at deploying a GitHub Action to build
Pandoc-flavored Markdown documents into their final forms. At present,
only DOCX and PDF are supported. It is hoped that future actions will
restore support for HTML, once the styles are cleaned up and aligned.

Dockerfile

@@ -0,0 +1,23 @@
+FROM pandoc/latex:2.9.2.1
+
+# Install the necessary LaTeX packages
+RUN tlmgr install \
+  crimsonpro \
+  sourcecodepro \
+  sourcesanspro \
+  sourceserifpro \
+  titlesec \
+  tocloft
+
+# Install bash
+RUN apk add bash
+
+RUN mkdir -p /cabforum
+RUN mkdir -p /cabforum/templates
+RUN mkdir -p /cabforum/filters
+
+COPY entrypoint.sh /cabforum/entrypoint.sh
+COPY templates/ /cabforum/templates/
+COPY filters/ /cabforum/filters/
+
+ENTRYPOINT ["/cabforum/entrypoint.sh"]

README.md

@@ -0,0 +1,65 @@
+# CA/Browser Forum Guidline builder action
+
+This action customizes the [Pandoc dockerfiles](https://github.com/pandoc/dockerfiles)
+for use by [CA/Browser Forum](https://www.cabforum.org) Chartered Working
+Groups to automatically produce Draft and Final Guidelines.
+
+## Inputs
+
+### `markdown-file`
+
+**Required** The name of the Markdown file to convert. This should be relative
+to [`GITHUB_WORKSPACE`](https://docs.github.com/en/free-pro-team@latest/actions/reference/environment-variables).
+
+In general, running [`actions/checkout`](https://github.com/actions/checkout)
+for the CWG repository is a necessary step before invoking this action, and
+allows just passing the filename relative to the current repository.
+
+### `pdf`
+
+Generate a PDF from `markdown-file`. Default: `"true"`.
+
+The resulting PDF will be in the same directory of `GITHUB_WORKSPACE` as the
+input file, but with a `pdf` extension.
+
+### `docx`
+
+Generate a DOCX. Default: `"true"`.
+
+The resulting PDF will be in the same directory of `GITHUB_WORKSPACE` as the
+input file, but with a `docx` extension.
+
+### `lint`
+
+Check that all self-referencing links resolve. Default: `"false"`.
+
+This runs a simple [Pandoc Lua filter](https://pandoc.org/lua-filters.html) to
+check and make sure that links to section headers resolve. Note that Pandoc
+removes leading numbers for sections, so the following would be valid:
+
+```
+# 1.1 Good Example
+
+This is a link to the [Good Example](#good-example)
+```
+
+But this would fail:
+```
+# 1.1 Broken Example
+
+This is a link to the [broken example](#1.1-broken-example)
+```
+
+### `draft`
+
+Add a "DRAFT" watermark to the resulting document. Default: `"false"`
+
+This is currently only supported for PDF outputs.
+
+## Example usage
+
+uses: cabforum/build-guidelines-action@v1
+with:
+  markdown-file: docs/BR.md
+  draft: true
+  lint: true

action.yml

@@ -0,0 +1,27 @@
+name: 'Build CA/Browser Forum Guideline'
+description: 'Convert a Pandoc-flavored Markdown file to PDF and DOCX using the CA/B Forum Guideline template'
+inputs:
+  markdown-file:
+    description: 'Name of the file to convert'
+    required: true
+  pdf:
+    description: 'Generate a PDF file (true/false)'
+    required: false
+    default: 'true'
+  docx:
+    description: 'Generate a DOCX (true/false)'
+    required: false
+    default: 'true'
+  lint:
+    description: 'Check for broken self-reference links (true/false)'
+    required: false
+    default: 'false'
+  draft:
+    description: 'Include a draft watermark (PDF-only for now) (true/false)'
+    required: false
+    default: 'false'
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - ${{ inputs.markdown-file }}

entrypoint.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+set -euo pipefail
+
+INPUT_DRAFT="${INPUT_DRAFT:-false}"
+INPUT_PDF="${INPUT_PDF:-true}"
+INPUT_DOCX="${INPUT_DOCX:-true}"
+INPUT_LINT="${INPUT_LINT:-false}"
+
+if [ "$#" -ne 1 ]; then
+  echo "No markdown file specified"
+  echo "Usage: $0 <markdown-file.md>"
+  exit 1
+fi
+if [ ! -f "$1" ]; then
+  echo "Invalid file specified: ${1} cannot be found."
+  exit 1
+fi
+if [ "${1##*.}" != "md" ] ; then
+  echo "Invalid file specified: ${1} is not a Markdown file."
+  exit 1
+fi
+BASE_FILE="${1%.*}"
+
+PANDOC_ARGS=( -f markdown --table-of-contents -s )
+
+if [ "$INPUT_DRAFT" = "true" ]; then
+  echo "Draft\n"
+  PANDOC_ARGS+=( -M draft )
+fi
+
+# Build PDF
+if [ "$INPUT_PDF" = "true" ]; then
+  echo "::group::Building PDF"
+  PANDOC_PDF_ARGS=( "${PANDOC_ARGS[@]}" )
+  PANDOC_PDF_ARGS+=( -t latex --pdf-engine=xelatex )
+  PANDOC_PDF_ARGS+=( --template=/cabforum/templates/guideline.latex )
+  PANDOC_PDF_ARGS+=( -o "${BASE_FILE}.pdf" "${1}" )
+
+  echo "::debug::${PANDOC_PDF_ARGS[@]}"
+  TEXINPUTS="$TEXINPUTS":/cabforum/ pandoc "${PANDOC_PDF_ARGS[@]}"
+  echo "::endgroup::"
+fi
+
+if [ "$INPUT_DOCX" = "true" ]; then
+  echo "::group::Building DOCX"
+  PANDOC_DOCX_ARGS=( "${PANDOC_ARGS[@]}" )
+  PANDOC_DOCX_ARGS+=( -t docx )
+  PANDOC_DOCX_ARGS+=( --reference-doc=/cabforum/templates/guideline.docx )
+  PANDOC_DOCX_ARGS+=( -o "${BASE_FILE}.docx" "${1}" )
+
+  echo "::debug::${PANDOC_DOCX_ARGS[@]}"
+  pandoc "${PANDOC_DOCX_ARGS[@]}"
+  echo "::endgroup::"
+fi
+
+if [ "$INPUT_LINT" = "true" ]; then
+  echo "::group::Checking links"
+  PANDOC_LINT_ARGS=( "${PANDOC_ARGS[@]}" )
+  PANDOC_LINT_ARGS+=( -t gfm )
+  PANDOC_LINT_ARGS+=( --lua-filter=/cabforum/filters/broken-links.lua )
+  PANDOC_LINT_ARGS+=( -o /dev/null "${1}" )
+
+  echo "::debug::${PANDOC_LINT_ARGS[@]}"
+  pandoc "${PANDOC_LINT_ARGS[@]}"
+  echo "::endgroup::"
+fi

filters/broken-links.lua

@@ -0,0 +1,35 @@
+--[[
+-- From https://github.com/jgm/pandoc/issues/1621#issuecomment-613336520
+--
+-- A simple Lua filter to warn about broken anchors to self. This doesn't
+-- handle concatenation of multiple Markdown files, so caveat emptor.
+--
+-- The only modification is to output to stderr in a way that GitHub
+-- Actions handle. See
+-- https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#setting-an-error-message
+--]]
+local identifiers = {}
+
+function Block (b)
+  if b.identifier then
+    identifiers[b.identifier] = true
+  end
+end
+
+function Inline (i)
+  if i.identifier then
+    identifiers[i.identifier] = true
+  end
+end
+
+function Link (l)
+  local anchor = l.target:match('#(.*)')
+  if anchor and not identifiers[anchor] then
+    io.stdout:write("::error::Unable to resolve link to " .. anchor .. "\n")
+  end
+end
+
+return {
+  {Block = Block, Inline = Inline},
+  {Link = Link}
+}

templates/guideline.latex

@@ -0,0 +1,158 @@
+\PassOptionsToPackage{dvipsnames,svgnames*,x11names*}{xcolor}
+
+\documentclass[
+  12pt,
+]{report}
+
+% Set up margins
+\usepackage[margin=1in]{geometry}
+
+% Configure fonts
+\usepackage{lmodern}  % TODO: Replace me
+\usepackage{unicode-math}
+\defaultfontfeatures{Scale=MatchLowercase}
+\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\usepackage[default]{sourceserifpro}
+\usepackage[ttdefault]{sourcecodepro}
+\usepackage{sourcesanspro}
+
+% For adding the logo to the title page
+\usepackage{graphicx}
+
+% Used by Pandoc tables
+\usepackage{longtable,booktabs}
+
+% Configure colors
+\usepackage{xcolor}
+\definecolor{TitleColor}{HTML}{335B8A}
+\definecolor{HeadingColor}{HTML}{4F81BD}
+\definecolor{HyperlinkColor}{HTML}{1155CC}
+
+% Configure links and PDF meta-data
+\usepackage[xetex, bookmarks, colorlinks, breaklinks]{hyperref}
+\hypersetup{
+  pdftitle={$title-meta$},
+  pdfauthor={$author-meta$},
+  colorlinks=true,
+  urlcolor=HyperlinkColor,
+  linkcolor=HyperlinkColor
+}
+\urlstyle{same}  % Style links the same as the surrounding text.
+
+% Cleanup spaces after periods
+\frenchspacing{}
+
+% Add the subtitle to \maketitle
+\usepackage{etoolbox}
+
+% Configure the table of contents
+\usepackage{tocloft}
+\cftsetindents{section}{1em}{1em}
+\cftsetindents{subsection}{2em}{1em}
+\cftsetindents{subsubsection}{3em}{1em}
+\cftsetindents{paragraph}{4em}{1em}
+
+% Disable per-paragraph indenting
+\usepackage{parskip}[indent=0pt]
+
+% Configure section styling
+\usepackage[compact]{titlesec}
+\titleformat{\section}[hang]{\clearpage\sourcesanspro\Large\bfseries\color{TitleColor}}{}{0.5pt}{}
+\titleformat{\subsection}[hang]{\sourcesanspro\Large\bfseries\color{HeadingColor}}{}{0.5pt}{}
+\titleformat{\subsubsection}[hang]{\sourcesanspro\large\bfseries\color{HeadingColor}}{}{0.5pt}{}
+\titleformat{\paragraph}[hang]{\sourcesanspro\normalsize\bfseries\color{HeadingColor}}{}{0.5pt}{}
+\titleformat{\subparagraph}[hang]{\sourcesanspro\normalsize\itshape\color{HeadingColor}}{}{0.5pt}{}
+\titlespacing*{\section}{0em}{1ex}{\parskip}
+\titlespacing*{\subsection}{0em}{1ex}{\parskip}
+\titlespacing*{\subsubsection}{0em}{1ex}{\parskip}
+\titlespacing*{\paragraph}{0em}{\baselineskip}{-\baselineskip}
+\titlespacing*{\subparagraph}{0em}{\baselineskip}{-\baselineskip}
+
+% Remove section numbering, since we number inline.
+\setcounter{secnumdepth}{-\maxdimen}
+
+% Redefines (sub)paragraphs to behave more like sections
+\ifx\paragraph\undefined\else
+	\let\oldparagraph\paragraph
+	\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
+\fi
+\ifx\subparagraph\undefined\else
+	\let\oldsubparagraph\subparagraph
+	\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
+\fi
+
+% Disable justification/hyphenation
+\raggedright
+
+% Configure page footer
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+\renewcommand{\headrulewidth}{0pt}
+\fancyfoot[R]{\color{HeadingColor}pg. \thepage}
+\fancypagestyle{plain}
+
+% Pandoc likes to use "tightlist" to reduce vertical whitespace; carried
+% over from the base template.
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}
+  \setlength{\parskip}{0pt}
+}
+
+% Add a watermark for drafts
+$if(draft)$
+\usepackage{draftwatermark}
+$endif$
+
+% Document metadata
+\title{$title$}
+\author{$for(author)$$author$$sep$ \and $endfor$}
+\date{$date$}
+
+% Layout the actual document
+\begin{document}
+
+% Coverpage
+\begin{titlepage}
+  \begin{center}
+    {\huge\bfseries {\color{TitleColor}$title$}}
+
+    $if(subtitle)$
+    \vspace{1cm}
+    {\Large\bfseries {\color{TitleColor}$subtitle$}}\\[15pt]
+    $endif$
+
+    \vspace{2cm}
+
+    \includegraphics[width=0.5\textwidth]{templates/cabforum.png}\\[5pt]
+    {$date$}
+
+    \vfill
+
+    {\small $copyright$}
+  \end{center}
+\end{titlepage}
+
+% Table of contents
+{
+  % Don't color links in the ToC
+  \hypersetup{linkcolor=}
+
+  % Show paragraphs in the ToC
+  \setcounter{tocdepth}{4}
+
+  % Make the ToC more compact
+  \renewcommand\cftdotsep{0.5}
+  \renewcommand\cftsetrmarg{0}
+
+  % Make the title pretty
+  \renewcommand*\contentsname{\sffamily\color{HeadingColor}{Table of Contents}}
+
+  \newpage
+  \tableofcontents
+  \newpage
+}
+
+$body$
+
+\end{document}