feat(docs): also use github-flavored markdown at the shuttle level

fixes [datasheet-backslash-issue]

docs/doc_header.md.mustache

@@ -4,17 +4,25 @@ title: |
     {{name}} Datasheet
 subtitle: Project Repository [{{repo}}]({{repo}})
 documentclass: scrartcl
-date: \today{}
+date: |
+```{=latex}
+\today{}
+```
 geometry: "left=2cm,right=2cm,top=2cm,bottom=2.5cm"
 fontsize: 14pt
 mainfont: Latin Modern Sans
 header-includes:
-- \usepackage{hyperref}
-- \hypersetup{colorlinks=true,
+- |
+  ```{=latex}
+  \usepackage{hyperref}
+  \hypersetup{colorlinks=true,
           urlcolor=blue,
           linkcolor=[rgb]{0,0,0.5},
           allbordercolors={0 0 0},
           pdfborderstyle={/S/U/W 1} }
+  ```
 ---
 
+```{=latex}
 \pagebreak
+```

documentation.py

@@ -121,40 +121,36 @@ def write_datasheet(self, markdown_file: str, pdf_file: Optional[str] = None):
 
                 logging.info(f"building datasheet for {project}")
 
-                # ensure there are no LaTeX escape sequences in various fields, and that optional fields are set
+                # ensure that optional fields are set
                 for key in [
                     "author",
                     "description",
                     "clock_hz",
                     "git_url",
                     "doc_link",
                 ]:
-                    if key in yaml_data:
-                        yaml_data[key] = str(yaml_data[key]).replace(
-                            "\\", "\\mbox{\\textbackslash}"
-                        )
-                    else:
+                    if key not in yaml_data:
                         yaml_data[key] = ""
 
                 # now build the doc & print it
                 try:
                     doc = chevron.render(doc_template, yaml_data)
                     fh.write(doc)
-                    fh.write("\n\\clearpage\n")
+                    fh.write("\n```{=latex}\n\\clearpage\n```\n")
                 except IndexError:
                     logging.warning("missing pins in info.yaml, skipping")
 
             # ending
             fh.write(doc_pinout)
-            fh.write("\n\\clearpage\n")
+            fh.write("\n```{=latex}\n\\clearpage\n```\n")
             fh.write(doc_info)
-            fh.write("\n\\clearpage\n")
+            fh.write("\n```{=latex}\n\\clearpage\n```\n")
             fh.write(doc_credits)
 
         logging.info(f"wrote markdown to {markdown_file}")
 
         if pdf_file is not None:
-            pdf_cmd = f"pandoc --toc --toc-depth 2 --pdf-engine=xelatex -i {markdown_file} -o {pdf_file}"
+            pdf_cmd = f"pandoc --toc --toc-depth 2 --pdf-engine=xelatex -i {markdown_file} -o {pdf_file} --from gfm+raw_attribute+smart+attributes"
             logging.info(pdf_cmd)
             p = subprocess.run(pdf_cmd, shell=True)
             if p.returncode != 0:

project.py

@@ -864,7 +864,7 @@ def create_pdf(self):
             except IndexError:
                 logging.warning("missing pins in info.yaml, skipping")
 
-        pdf_cmd = "pandoc --pdf-engine=xelatex --resource-path=docs -i datasheet.md -o datasheet.pdf --from gfm+raw_attribute+smart"
+        pdf_cmd = "pandoc --pdf-engine=xelatex --resource-path=docs -i datasheet.md -o datasheet.pdf --from gfm+raw_attribute+smart+attributes"
         logging.info(pdf_cmd)
         p = subprocess.run(pdf_cmd, shell=True)
         if p.returncode != 0: