RyanGreenup/Using-tikz-in-markup.org

## Using-tikz-in-markup.org

      
    Raw
  

              Using-tikz-in-markup.org
            
          
    Using TikZ in Markup Languages

Introduction

So consider the tikz code at listing tikz-eg1 and figure Tikz-out1:
\begin{tikzpicture}
\draw[->] (-3,0) -- (-2,0) arc[radius=0.5cm,start angle=-180,end angle=0] (-1,0) -- (1,0) arc[radius=0.5cm,start angle=180,end angle=0] (2,0) -- (3,0);
\filldraw (-1.5,0) circle[radius=1mm];
\filldraw (1.5,0) circle[radius=1mm];
\end{tikzpicture}
Let’s consider how to use this inside org-mode and Markdown.
Org-Mode

Using a Source Code Block for Tikz

Using the code provided in listing tikz-eg-manyline, will allow $\textrm{Ti}\textit{k}\textrm{Z}$ code to be exported from org-mode as $\LaTeX$ and HTML.
#+LATEX_HEADER: \usepackage{svg}
#+LATEX_HEADER: \usepackage{tikz}

#+NAME: tikz-eg-oneline
#+CAPTION: How to produce Tikz in Org-mode

#+HEADER: :exports results
#+HEADER: :imagemagick yes
#+HEADER: :results output graphics file
#+HEADER: :file contour.svg
#+BEGIN_SRC latex
\begin{tikzpicture}
\draw[->] (-3,0) -- (-2,0) arc[radius=0.5cm,start angle=-180,end angle=0] (-1,0) -- (1,0) arc[radius=0.5cm,start angle=180,end angle=0] (2,0) -- (3,0);
\filldraw (-1.5,0) circle[radius=1mm];
\filldraw (1.5,0) circle[radius=1mm];
\end{tikzpicture}
#+END_src
Explaining the Header Arguments


  #+LATEX_HEADER
Add arguments to the $\LaTeX$ preamble when performing org-mode export to $\LaTeX$.
    
      usepackage{svg}
This package converts an SVG image back to a PNG so that it can be included in a LaTeX Document.
      usepackage{TikZ}
The TikZ package, necessary to generate TikZ graphics.
    
    
      These should be put at the very top of an org file much like a preamble, they affect the entire buffer and only need to be added once.
    
    
      WARNING
If these are included in a .sty file, take note of the following points:
        
          
$\LaTeX$ does not support ~, instead use $HOME

          In a .sty file \RequirePackage{foo} should be used instead of usepackage

          The correct syntax is to drop the .sty extension in the preamble
            
              so to use the stylesheet ~/Templates/mystyle.sty use the following header argument at the top of the top of the org-file ,#+LATEX_HEADER: \usepackage{$HOME/Templatex/mystyle}

            
  ,#+NAME:
This gives the listing a name so that later it can be referred to using the [[foo]] syntax
    
      Be mindful that this is distinct from the org-ref ref:label-name syntax.
      Also be aware that this usually must be pared with a caption for it to be referencable in $\LaTeX$.
    
  
  ,#+CAPTION:
This gives the listing a caption to describe it and provide a place to put the number.
    
      WARNING
If the source code block is switched from :output both to :output results the code block will not be shown in the latex export, this means that there will be nothing for a [[foo]] link to refer to even if there is a ,#+NAME:foo header. So be very careful about referring to a code block that you are unsure of including in the output because it can cause headaches.
    
  
  #+HEADER
Add arguments to the header of a source code block, these could just as easily be done in one line as shown in listing ??
    
      :exports
This controls what is exported
        
          both
for the code and the output
          code
for only the code
          results
Exports only the results?
            
              ~output~
This is incorrect Syntax, don’t use it, I don’t know why, but I always always type in :exports output which is incorrect, it should be :exports results and then :results output or whatever you want the results to be.
            
          
      results
This controls what contitutes the output
        
          :results output
This provide the STDOUT, consider for example ls in bash
          :results output graphics file
This will provide any graphics output as a file and link to that file as an inline image in the results.
            
              This is necessary for the TikZ picture to be included as output (It’s also necessary for using ggplot as well)
            
          
      :imagemagick
Ensures that imagemagick is used (which is needed to convert the PDF to SVG).
      :file
Gives the File name to save the output graphic as, you’ll need to remember to change this.
        
          I played around with automatically generating a random name, but, it’s more effort than it’s worth and being forced to come up with semi-descriptive names promotes sanity.
        
      
      If a header argument will occur often throughout a buffer the ,#+PROPERTY: header-args:  to apply standard settings across the src code blocks
        
          For example ,#+HEADER :eval never-export can be placed at the top of the org file to ensure that every source code block will behave as if :eval never-export was in the src code block header, meaning, the code block won’t evaluate on export (very helpful for note on /R/ for example)
        
      
One Line

It may be more convenient to use the following syntax to keep the src header on one line (presuming ,#+LATEX_HEADER is provided at the top of the org file) as shown in listing :
\begin{tikzpicture}
\draw[->] (-3,0) -- (-2,0) arc[radius=0.5cm,start angle=-180,end angle=0] (-1,0) -- (1,0) arc[radius=0.5cm,start angle=180,end angle=0] (2,0) -- (3,0);
\filldraw (-1.5,0) circle[radius=1mm];
\filldraw (1.5,0) circle[radius=1mm];
\end{tikzpicture}
\#+END_src
Preview Tikz Inside Org Mode Without a Source Block

Tikz can be previewed inline using the The texfrag package, this means that the TikZ will only be visible in $\LaTeX$ output, or inline in the org file.
Using TikZ this way doesn’t bring much to the table over using the source code block discussed at section #generating-functions and shown in listing tikz-eg-manyline but is more convenient if:

  The document will only go to $\LaTeX$
    
      In which case having raw TikZ as opposed to an SVG file in the .tex would be much more ideal
    
  
  The texfrag package is being used
    
      I can’t get org-latex-preview to work with TikZ and TexFrag is faster and scales the pictures automatically, so it’s superior anyway.
    
  
In order to get an inline preview of TikZ code, put the LISP provided at listing lisp-for-tikz-preview  in the ~/.emacs.d/config.el (or execute the src block in the org buffer and then M-x org-mode Ret)
(add-hook 'org-mode-hook
  (lambda ()
    (texfrag-mode)
  )

(add-to-list 'org-latex-packages-alist
             '("" "tikz" t))
(eval-after-load "preview"
  '(add-to-list 'preview-default-preamble "\\PreviewEnvironment{tikzpicture}" t))
place some raw TikZ code in the document and run M-x texfrag-document and the TikZ code should be previewed in place.
Markdown

UpMath
Upmath is essentially an awesome piece of JavaScript that will render Tikz in place, It’s very cool and compatible with pandoc –> LaTeX.
To use it just put the following code from listing use-upmath-tikz-md into a MarkDown file (if using VSCode make sure that the markdown file can execute arbitrary script and/or consider making a local copy of the JavaScript as shown in listing local-js):
<p>
<script src="https://i.upmath.me/latex.js"></script>
\begin{tikzpicture}
\draw[->] (-3,0) -- (-2,0) arc[radius=0.5cm,start angle=-180,end angle=0] (-1,0) -- (1,0) arc[radius=0.5cm,start angle=180,end angle=0] (2,0) -- (3,0);
\filldraw (-1.5,0) circle[radius=1mm];
\filldraw (1.5,0) circle[radius=1mm];
\end{tikzpicture}
</p>
Local JS

Alternatively if you want to have a local copy of the JS, consider downloading the JavaScript as shown in listing dl-js and then create a Markdown File referencing that JS accordingly as shown in listing local-js. This however will not work offline, although self-hosting or a local-server is an option, See the corresponding GitHub page.
curl https://i.upmath.me/latex.js > ~/bin/upmath-latex.js > /tmp/upmath-latex.js
<p>
<script src="https://i.upmath.me/latex.js"></script>
\begin{tikzpicture}
\draw[->] (-3,0) -- (-2,0) arc[radius=0.5cm,start angle=-180,end angle=0] (-1,0) -- (1,0) arc[radius=0.5cm,start angle=180,end angle=0] (2,0) -- (3,0);
\filldraw (-1.5,0) circle[radius=1mm];
\filldraw (1.5,0) circle[radius=1mm];
\end{tikzpicture}
</p>
Exporting to LaTeX

To Export this markdown to LaTeX, create a /tmp/mystyle.sty file that has \RequirePackage{tikz, pstricks, pgfplots, amsmath} in it somewhere and use the call to pandoc as shown in listing simple-pandoc. Listing pandoc-with-listings is what I usually use to get formatted code via the listings package.
pandoc -s --self-contained "/tmp/mymarkdown.md" -H /tmp/mystyle.sty -o /tmp/note.pdf
pandoc -s --self-contained "/tmp/mymarkdown.md" --listings --toc -H ~/Templates/LaTeX/Mystyle.sty --pdf-engine-opt=-shell-escape -o /tmp/note.pdf
Markdown Preview Enhanced

Markdown Preview-Enhanced in Atom and VSCode also allow previewing TikZ Code which I personally think is really handy.
It just doesn’t work with pandoc because the TikZ code is wrapped in a code block.
Also worth mentioning that UpMath doesn’t appear to work with Markdown Preview Enhanced.
/R/-/Markdown/

Probably worth noting that /R/-/Markdown/ does this pretty much out of the
  box, so you could just write up a document in /R/-/Markdown/ with TikZ and
  then export it to HTML/MD/PDF. Using /R/-/Studio/ to perform all the knitR
  magic is quite painless as well.