Notes on generating wiki pdf - NOC-MSM/SRIL34 GitHub Wiki

Obtain wikidoc code

git clone https://github.com/jpolton/wikidoc A handy utility to convert GitHub wiki docs into a PDF. Requires "invisible" HTML tags edits to wiki files. Updated for python3.

Install library

I had to install wkhtmltopdf . if you are in NOCL, the library is already installed on livljobs, load the module with module load wkhtmltopdf/0.12.6.

Edit Home.md

Edit Home.md to include HTML header information (as in the wikidoc README)

In particular edit:

  • line 2: which include the pdf filename
  • line 46: which include the pdf cover title.

E.g.

<!-- WIKIDOC CONFIG
--filename SEAsia_Apr22.pdf
--page-size A4
--margin-top 2cm
--margin-left 2cm
--margin-bottom 2cm
--margin-right 2cm
--footer-font-name Verdana
--footer-font-size 6
--footer-spacing 10
--footer-right [page]
WIKIDOC CONFIG -->

<!-- WIKIDOC HTMLHEAD
<html>
 <head>
  <STYLE type='text/css'>
	html { font-family: Verdana, Geneva, sans-serif; font-size: 13px; }
	.covertitle { padding-top: 40%; text-align: right; font-size: 40px; }
	.generated { font-size: 12px; }

	table { border-collapse: collapse;  margin: 1em auto 1em auto; width: 90%; border: 1px solid #ccc; }
	tr td:first-child { border-right: 1px solid #ccc; width: 2.5cm !important;  }
	table tr:first-child { background-color: #ddd; }
	table td { font-family: Verdana,Geneva,sans-serif; font-size: 8pt; vertical-align: top; padding: 5px; }

	h1 { page-break-before: always; font-size: 26.6px; }
	h2 { margin-top: 3ex; font-size: 20px; }
	h3 { margin-top: 3ex; 13.3px}

	.breakbefore { page-break-before: always; }
	.wiki_only { display: none; }
  </STYLE>
 </head>
 <body>
WIKIDOC HTMLHEAD -->

<!-- WIKIDOC HTMLFOOT
 </body>
</html>
WIKIDOC HTMLFOOT -->

<!-- the following WIKIDOC comments are optional -->

<!-- WIKIDOC COVER
<div class='covertitle'><b>SEAsia</b> Documentation<br><span class='generated'>generated from https://github.com/NOC-MSM/SEAsia/wiki: ###_WIKIDOC_GENDATE_###</span></div>
WIKIDOC COVER -->

<!-- WIKIDOC TOCXSL
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:outline="http://wkhtmltopdf.org/outline"
                xmlns="http://www.w3.org/1999/xhtml">
  <xsl:output doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"
              doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
              indent="yes" />
  <xsl:template match="outline:outline">
    <html>
      <head>
        <title>Contents</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <style>
          h1 {
            text-align: left;
            font-size: 26.6px;
            font-family: verdana;
          }
          div {border-bottom: 1px dashed rgb(200,200,200);}
          span {float: right;}
          li {list-style: none;}
          ul {
            font-size: 13px;
            font-family: verdana;
          }
          ul ul {font-size: 85%; }
          ul {padding-left: 0em; }
          ul ul {padding-left: 1em;}
          a {text-decoration:none; color: black;}
          ul.toplevel li { margin-bottom: 1em;  }
          ul.sublevels li { margin-bottom: 0em;  }
          ul li:last-child { margin-bottom: 1em; }
        </style>
      </head>
      <body>
        <h1>Contents</h1>
        <ul class="toplevel"><xsl:apply-templates select="outline:item/outline:item"/></ul>
      </body>
    </html>
  </xsl:template>
  <xsl:template match="outline:item">
     <li>
      <xsl:if test="(@title!='') and (@title!='Contents')">
        <div>
          <a>
            <xsl:if test="@link">
              <xsl:attribute name="href"><xsl:value-of select="@link"/></xsl:attribute>
            </xsl:if>
            <xsl:if test="@backLink">
              <xsl:attribute name="name"><xsl:value-of select="@backLink"/></xsl:attribute>
            </xsl:if>
            <xsl:value-of select="@title" />
          </a>
          <span> <xsl:value-of select="@page" /> </span>
        </div>
      </xsl:if>
      <ul class="sublevels">
        <xsl:comment>added to prevent self-closing tags in QtXmlPatterns</xsl:comment>
        <xsl:apply-templates select="outline:item"/>
      </ul>
    </li>
  </xsl:template>
</xsl:stylesheet>
WIKIDOC TOCXSL -->

<!-- end of wikidoc config section -->

Add a HTML header to each page

Edit each wiki page, adding

<!-- WIKIDOC PDFONLY
<h1>###_WIKIDOC_TITLE_###</h1>
WIKIDOC PDFONLY -->

to the top of each page so that the file name is included as the page header

Compile pdf

In a python environment execute the following. (I used python=3.8 but think it was an otherwise vanilla conda environment. E.g. conda create --name wikidoc_env python=3.8. Then conda activate wikidoc_env). Then from within the wikidoc repo directory:

python wikidoc.py <path-to-wkhtmltopdf> <path-to-wiki-repo>

E.g.

python wikidoc.py /usr/local/bin/wkhtmltopdf ~/GitHub/SEAsia.wiki

The PDF is generated in the repo directory.

If you are in NOCL, log into the livljobs server with ssh -X livljobs, and after editing the pages and activating your conda environment, load the libraries with module load wkhtmltopdf/0.12.6 and run:

python wikidoc.py /packages/modules/apps/wkhtmltopdf/0.12.6/local/bin/wkhtmltopdf <path-to-wiki-repo>

⚠️ **GitHub.com Fallback** ⚠️