Generate document with table of contents containing page numbers using Markdown or something similar?

Question

I need to create a large document that when printed will be a couple hundred pages. I’d like to do this with something like Markdown. One of my requirements is that the document must have page numbers and a table of contents. Is there a way using Markdown or a similar Markup language to automatically generate a table of contents with associated page numbers? All the stuff I’ve sceen with Markdown so far can automatically generate a table of contents for HTML output but there are no associated page numbers.

Solution 1

Sounds like a job for pandoc.

HTML has no concept of 'pages'; it would probably be possible to kludge something together with <div></div> tags, but I'd just use PDF:

pandoc --toc --chapters -o output.pdf input1.mkd input2.mkd

Pandoc can take an arbitrary number of inputs; it adds a newline to the end of each input and concatenates them. The above command will create a PDF designed to be bound as a book - each chapter (signified by a level 1 title) will start on an odd-numbered page. If you don't want this behaviour, use the following:

pandoc --toc -V documentclass=report -o output.pdf input1.mkd input2.mkd

If you want to save paper and don't mind about chapters just starting wherever the previous one ends (they will even start in the middle of a page), call pandoc without the --chapters option:

pandoc --toc -o output.pdf input1.mkd input2.mkd

You can generate a HTML with a table of contents, but with all the limitations that you listed. It is also possible to generate ODT and Microsoft DOC documents with pandoc, but I think they don't look very good, especially compared to the beautiful PDF generation.

Creating PDFs with pandoc requires a LaTeX engine to be installed; this is pretty trivial on Linux, where you'll have at least one in the repositories, but on Windows it might be a little harder (I wouldn't know, I've never actually tried). As such, it is possible to customise things to your liking with a custom LaTeX template - but I haven't got my head around that yet, so I currently stick with the (pretty nice) defaults.

Solution 2

After some google minutes I noticed that you need your own LaTeX-Template which can passed as an option to pandoc:

pandoc --toc --chapter --template=yourtemplate.tex -o output.pdf input1.mkd

However your template needs some modification on the LaTeX site. As a suggestion you can use:

As a starting point you can use the following template. I copied the default template https://github.com/jgm/pandoc-templates/blob/master/default.latex and added some extra stuff.

I am sure that you can remove most of the if-end-combinations. The template needs it to have more options for users.

\documentclass[chapterprefix=false,titlepage=false]{scrreprt}
\usepackage[T1]{fontenc}

\usepackage{amssymb,amsmath}
\usepackage{fixltx2e} % provides \textsubscript
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[utf8]{inputenc}
$if(euro)$
  \usepackage{eurosym}
$endif$
\else % if luatex or xelatex
  \ifxetex
    \usepackage{mathspec}
    \usepackage{xltxtra,xunicode}
  \else
    \usepackage{fontspec}
  \fi
  \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase}
  \newcommand{\euro}{€}
$if(mainfont)$
    \setmainfont{$mainfont$}
$endif$
$if(sansfont)$
    \setsansfont{$sansfont$}
$endif$
$if(monofont)$
    \setmonofont{$monofont$}
$endif$
$if(mathfont)$
    \setmathfont(Digits,Latin,Greek){$mathfont$}
$endif$
\fi
% use microtype if available
\IfFileExists{microtype.sty}{\usepackage{microtype}}{}
$if(geometry)$
\usepackage[$for(geometry)$$geometry$$sep$,$endfor$]{geometry}
$endif$
$if(natbib)$
\usepackage{natbib}
\bibliographystyle{plainnat}
$endif$
$if(biblatex)$
\usepackage{biblatex}
$if(biblio-files)$
\bibliography{$biblio-files$}
$endif$
$endif$
$if(listings)$
\usepackage{listings}
$endif$
$if(lhs)$
\lstnewenvironment{code}{\lstset{language=Haskell,basicstyle=\small\ttfamily}}{}
$endif$
$if(highlighting-macros)$
$highlighting-macros$
$endif$
$if(verbatim-in-note)$
\usepackage{fancyvrb}
$endif$
$if(tables)$
\usepackage{longtable}
$endif$
$if(graphics)$
\usepackage{graphicx}
% Redefine \includegraphics so that, unless explicit options are
% given, the image width will not exceed the width of the page.
% Images get their normal width if they fit onto the page, but
% are scaled down if they would overflow the margins.
\makeatletter
\def\ScaleIfNeeded{%
  \ifdim\Gin@nat@width>\linewidth
    \linewidth
  \else
    \Gin@nat@width
  \fi
}
\makeatother
\let\Oldincludegraphics\includegraphics
{%
 \catcode`\@=11\relax%
 \gdef\includegraphics{\@ifnextchar[{\Oldincludegraphics}{\Oldincludegraphics[width=\ScaleIfNeeded]}}%
}%
$endif$
\ifxetex
  \usepackage[setpagesize=false, % page size defined by xetex
              unicode=false, % unicode breaks when used with xetex
              xetex]{hyperref}
\else
  \usepackage[unicode=true]{hyperref}
\fi
\hypersetup{breaklinks=true,
            bookmarks=true,
            pdfauthor={$author-meta$},
            pdftitle={$title-meta$},
            colorlinks=true,
            urlcolor=$if(urlcolor)$$urlcolor$$else$blue$endif$,
            linkcolor=$if(linkcolor)$$linkcolor$$else$magenta$endif$,
            pdfborder={0 0 0}}
\urlstyle{same}  % don't use monospace font for urls
$if(links-as-notes)$
% Make links footnotes instead of hotlinks:
\renewcommand{\href}[2]{#2\footnote{\url{#1}}}
$endif$
$if(strikeout)$
\usepackage[normalem]{ulem}
% avoid problems with \sout in headers with hyperref:
\pdfstringdefDisableCommands{\renewcommand{\sout}{}}
$endif$
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
\setlength{\emergencystretch}{3em}  % prevent overfull lines
$if(numbersections)$
\setcounter{secnumdepth}{5}
$else$
\setcounter{secnumdepth}{0}
$endif$
$if(verbatim-in-note)$
\VerbatimFootnotes % allows verbatim text in footnotes
$endif$
$if(lang)$
\ifxetex
  \usepackage{polyglossia}
  \setmainlanguage{$mainlang$}
\else
  \usepackage[$lang$]{babel}
\fi
$endif$
$for(header-includes)$
$header-includes$
$endfor$

$if(title)$
\title{$title$}
$endif$
\author{$for(author)$$author$$sep$ \and $endfor$}
\date{$date$}

\begin{document}
$if(title)$
\maketitle
$endif$

$for(include-before)$
$include-before$

$endfor$
$if(toc)$
{
\hypersetup{linkcolor=black}
\setcounter{tocdepth}{$toc-depth$}
\begingroup
\let\clearpage\relax
\tableofcontents
\endgroup
}
$endif$
$body$

$if(natbib)$
$if(biblio-files)$
$if(biblio-title)$
$if(book-class)$
\renewcommand\bibname{$biblio-title$}
$else$
\renewcommand\refname{$biblio-title$}
$endif$
$endif$
\bibliography{$biblio-files$}

$endif$
$endif$
$if(biblatex)$
\printbibliography$if(biblio-title)$[title=$biblio-title$]$endif$

$endif$
$for(include-after)$
$include-after$

$endfor$
\end{document}

Solution 3

Have you considered using LaTeX?

The other answers suggest using Pandoc, which looks like it can convert Markdown to LaTeX, but it might be easier to start right in LaTeX.

LaTeX is designed for the creation of print documents, and has things like page numbers and TOC generation built-in. Check out this basic tutorial: http://www.andy-roberts.net/writing/latex

Comments

[tvdo]

Probably because HTML has no concept of page numbers. What is a page?

[Jared]

markdown doesn't have to be converted into HTML.

[killermist]

It sounds like what you're looking for is something like PDF, as opposed to something that ends up rendered in HTML/XHTML.

[nealmcb]

Note: to actually show a table of contents for html (without page numbers, naturally), you need both the --toc option AND the -s (standalone) option. I didn't find this documented anywhere....

[Jared]

Looks good and this is probably the solution I will go with.