Broken internal links in STONEWORK-CONFIG.pdf

[samuel-dudik]

The internal links in the PDF generated from docs/config/STONEWORK-CONFIG.md are broken. The .md file uses <a name=""/> HTML tags for internal links which are supported by Github markdown viewer, but not by pandocs (program used to generate PDFs) default PDF engine pdflatex. Implicit internal links (https://pandoc.org/MANUAL.html#internal-links) can't be used because resulting headers would be too long + add unnecessary noise and header attributes (https://pandoc.org/MANUAL.html#extension-header_attributes) don't seem to be supported by Github markdown.

Currently, the solution is to use a PDF engine that can interpret HTML tags e.g. weasyprint:

pandoc STONEWORK-CONFIG.md -o STONEWORK-CONFIG.pdf --pdf-engine=weasyprint -c style.css

style.css for proper table rendering:

body {
        font-size: 12px;
}

a {
        text-decoration: none;
}

table, th, td {
        border: 1px solid;
        border-collapse: collapse;
}

th, td {
        padding: 3px;
}

The problem is that weasyprint and the pandoc version supporting it aren't included in the Ubuntu 18.04 repositories. 18.04 is currently used for the Docker image responsible for STONEWORK-CONFIG.pdf generation. 20.04 does include all required packages by default. On 18.04 direct download and installation of pandoc and weasyprint binaries is required.

Further information and reference: https://github.com/PANTHEONtech/StoneWork/pull/12

[ondrej-fabry]

@samuel-dudik this was fixed by #12 correct?

[samuel-dudik]

No, it wasn't. We ended up adding pdfs to .gitignore, but pdfs generated by Makefile still contain broken links.