Skip to main content

Export Swimm docs

Export to PDF​

To optimize document sharing and compatibility across extended teams without direct Git integration, we recommend using Pandoc, a universal document converter, to export your Swimm documentation.

Since Swimm docs are created in Markdown format, Pandoc enables easy conversion to a variety of document types, such as Microsoft Word, HTML, PDF, LaTeX, and more. This flexibility is key for teams without traditional version control, facilitating collaboration on technical documentation.

Install Pandoc​

To install Pandoc, follow the instructions on the Pandoc installation page.

PDF Conversion with LaTeX​

To generate PDFs, Pandoc converts files to LaTeX and then to PDF. You'll need a TeX distribution like MacTeX.

Windows​

We recommend installing it via MiKTeX. With the option --pdf-engine, you however can specify other programs for this mask.

macOS​

Because a full MacTeX installation uses four gigabytes of disk space, we recommend BasicTeX or TinyTeX and using the tlmgr tool to install additional packages as needed. If you receive errors warning of fonts not found:

tlmgr install collection-fontsrecommended

With the option --pdf-engine, you however can specify other programs for this task.

Linux​

We recommend installing TeX Live via your package manager. (On Debian/Ubuntu, apt-get install texlive.) With the option --pdf-engine, you however can specify other programs for this task.

Convert to PDF​

To convert a Swimm document to PDF, use the following command in your terminal:

pandoc SwimmDoc.[hash].sw.md -o ConvertedSwimmDoc.pdf

Pandoc is highly customizable. You can control the look of your PDF by creating a custom LaTeX template or by using command-line options to specify document elements like headers, footers, and font sizes.

Unicode Support​

LaTeX can handle a wide range of characters, but support for full Unicode, especially for less common characters or emojis, can be limited without additional packages or configurations. Here are a few ways to address this issue:

1. Remove or replace Unicode characters​

  • The simplest solution might be to remove or replace the Unicode character(s) causing the issue if they're not essential to the document's content.

2. Use XeLaTeX or LuaLaTeX​

  • XeLaTeX and LuaLaTeX are more modern versions of LaTeX with better Unicode support. You can tell Pandoc to use one of these for PDF generation with the --pdf-engine option:
Terminal command with --pdf-engine option:​
pandoc SwimmDoc.[hash].sw.md -o ConvertedSwimmDoc.pdf --pdf-engine=xelatex

3. Specify a Font That Supports the Unicode Characters​

When using XeLaTeX or LuaLaTeX, you can specify a font that includes the Unicode characters in question. Use the --variable mainfont="Font Name" option.

Terminal command with --variable mainfont option:​
pandoc SwimmDoc.[hash].sw.md -o ConvertedSwimmDoc.pdf --pdf-engine=xelatex --variable mainfont="DejaVu Sans"
Make sure the font you choose is installed on your system and supports the Unicode characters you're using.

Customizing Documents with Pandoc's Header Option​

The --include-in-header=header.tex option in Pandoc can be used to customize the appearance and functionality of PDF documents generated from Markdown.

LaTeX commands such as \usepackage{fontspec} for font customization, or \usepackage{listings} for advanced code formatting, can enhance the readability and aesthetic of exported documents. This approach is ideal for creating technically detailed documents with specific formatting requirements for fonts and code blocks.

Example 1: header.tex file with listings package:​
\usepackage{fontspec}
\setmainfont{DejaVu Sans}
\newfontfamily{\fallbackfont}{Noto Color Emoji}
\DeclareTextFontCommand{\textfallback}{\fallbackfont}

\usepackage{listings}
\lstset{
  breaklines=true,      % Enable line wrapping for long lines
  basicstyle=\ttfamily\small, % Set code font size
  columns=fullflexible, % Use flexible spacing between characters
  tabsize=2,            % Sets the tab size to 2 spaces
  frame=single,         % Adds a frame around the code block
  framesep=5pt,         % Distance between frame and code
  xleftmargin=5pt,      % Left margin
  xrightmargin=5pt,     % Right margin
  captionpos=b          % Caption position at the bottom
}
Example 2: header.tex file with fvextra package + Verbatim environment:​

To enhance the display of source code in your Pandoc-generated documents, consider the fvextra package, which enables fine-tuned customization of Verbatim environments and allows for flexible line breaking, essential for maintaining readability in code blocks.

\usepackage{fvextra}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
Example 3: header.tex file with fvextra package:​

The fvextra package, when integrated with Pandoc, provides robust control over verbatim text presentation, including features such as breaklines and breakanywhere, ensuring that long code lines wrap and don't spill over the margins of your document.

\usepackage{fvextra}
\fvset{breaklines=true, breakanywhere=true}
Terminal command including the header.tex file and PDF engine xelatex:​
pandoc SwimmDoc.[hash].sw.md -o ConvertedSwimmDoc.pdf --pdf-engine=xelatex --include-in-header=header.tex
Terminal command including the header.tex file and PDF engine lualatex:​
pandoc SwimmDoc.[hash].sw.md -o ConvertedSwimmDoc.pdf --pdf-engine=lualatex --include-in-header=header.tex

This document is automatically kept up to date using Swimm.