Adding Line Numbers to Code Blocks in Markdown PDFs

Technical documentation, programming guides, and computer science papers often include code blocks. When readers need to follow step-by-step instructions or reference specific sections of code, having line numbers is extremely helpful.

In this tutorial, we will explore the best techniques to add line numbers code block markdown pdf documents can render, using both Pandoc compiler options and standard CSS stylesheet definitions.

Why Add Line Numbers to Code Blocks?

Line numbers in technical documents provide several benefits:

• Enhanced References: Authors can say “refer to line 12 in Listing 3” rather than describing the line location.
• Improved Code Structure: Line numbering visually separates long blocks of code and prevents confusion when lines wrap.
• Academic Standard: Computer science papers and textbooks require numbered lines for algorithms.

Method 1: Using Pandoc (With —number-lines Flag)

If you compile Markdown to PDF using Pandoc, the syntax highlighter supports line numbering natively.

YAML Header Configuration

To enable line numbers, define the code block using fenced code blocks and add the numberLines class inside the block’s attribute curly braces:

```{#mycode .python .numberLines}
def fibonacci(n):
    if n <= 0:
        return []
    elif n == 1:
        return [0]
    # ... computation details ...

When Pandoc processes this block during PDF compile, it will output line numbers starting at 1.

### Customizing Line Number Offsets

If you are displaying a snippet that starts mid-function, you can offset the starting line number using the `startFrom` attribute:

```markdown
```{.python .numberLines startFrom="15"}
    sequence = [0, 1]
    while len(sequence) < n:
        sequence.append(sequence[-1] + sequence[-2])
    return sequence

This starts numbering this specific block at line 15, matching the context of the larger source file.

## Method 2: CSS Rules (For Web-to-PDF Compilers)

If you render Markdown using an HTML-based compiler (like Weasyprint or Puppeteer), you can add line numbering using CSS counters.

### HTML Structure for Numbered Code Blocks

Ensure your markdown parser outputs code blocks where each line is wrapped in a span or list element. If each line is structured as a `span.line`, you can use CSS:

```html
<pre class="numbered-code"><code><span class="line">def hello_world():</span>
<span class="line">    print("Hello, World!")</span></code></pre>

CSS Counter Rules for Line Numbers

Use CSS counters to increment and display numbers on each line:

/* Initialize the line counter on the code block container */
.numbered-code code {
  counter-reset: line-counter;
}

/* Format each line container */
.numbered-code .line {
  display: block;
  position: relative;
  padding-left: 3em; /* Space reserved for numbers */
}

/* Generate the line numbers before each line */
.numbered-code .line::before {
  counter-increment: line-counter;
  content: counter(line-counter);
  position: absolute;
  left: 0;
  width: 2.5em;
  text-align: right;
  color: #a0aec0; /* Subdued color for numbers */
  font-size: 0.85em;
  border-right: 1px solid #e2e8f0;
  padding-right: 0.5em;
  user-select: none; /* Prevent copying of line numbers */
}

Method 3: JavaScript Syntax Highlighters (Prism.js / Highlight.js)

For developers exporting PDFs through browser print layouts, running client-side syntax highlighters can simplify the implementation:

• Prism.js: Include the line-numbers plugin. Add class="line-numbers" to the parent <pre> element.
• Highlight.js: Use third-party extensions like highlightjs-line-numbers.js to automatically split code elements into rows and append numbered columns.

Make Your Code Blocks Readable

Line numbering is an essential detail for publishing high-quality code listings. To write markdown, customize block properties, and quickly export to PDF with code numbers and highlighting, use our Markdown to PDF Editor.