Grid Print Formatting Guide

Grid Print Formatting Guide#

This guide explains how to properly format grid and grid-item-card directives for PDF output.

Overview#

The grid print formatting system ensures that:

  1. Each grid-item-card stays on a single page (no page breaks within cards)

  2. Layout is preserved based on the grid column specification

  3. Optimal spacing and formatting for print media

CSS Files#

Two CSS files handle grid print formatting:

  1. _static/grid_print.css (matematikk_r1 specific)

    • Comprehensive grid and card print styling

    • Column width definitions

    • Gutter spacing controls

    • Card content formatting

  2. munchboka-edutools/src/munchboka_edutools/static/css/print_pdf.css

    • Updated with basic grid print support

    • Integrated with other print features

Grid Directive Format#

The grid directive uses the format:

{grid} <xs> <sm> <md> <lg>

Where:

  • xs: phone portrait (< 576px)

  • sm: phone landscape (576px - 768px)

  • md: tablet (768px - 992px)

  • lg: desktop (> 992px) - This value is used for PDF output

Example#

{grid} 1 1 2 2

This means:

  • Mobile portrait: 1 column

  • Mobile landscape: 1 column

  • Tablet: 2 columns

  • Desktop/PDF: 2 columns (2 cards side-by-side)

Common Grid Configurations#

Grid Spec

Mobile

Tablet

PDF Layout

Use Case

1 1 2 2

1 col

2 cols

2 cards side-by-side

Overview pages, paired content

1 2 2 2

1 col

2 cols

2 cards side-by-side

Exercises, examples

1 1 2 3

1 col

2 cols

3 cards side-by-side

Multiple small items

1 1 1 1

1 col

1 col

1 card per row

Detailed content

Usage Example#

Here’s a complete example from your oversikt pages:

# Oversikt: Omvendte funksjoner

::::::::{grid} 1 1 2 2
---
gutter: 2
---
::::::{grid-item-card}
**Omvendte funksjoner**
^^^
**Definisjon**:
$f$ og $g$ er omvendte funksjoner hvis

$$
f(g(x)) = x \qog g(f(x)) = x
$$
::::::

::::::{grid-item-card}
**Grafisk sammenheng**
^^^
* Grafen til $f$ og $f^{-1}$ er speilet om linja $y = x$
::::::

::::::{grid-item-card}
**Eksistens av omvendte funksjoner**
^^^
En funksjon $f$ med definisjonsmengde $D_f$ har en omvendt funksjon hvis...
::::::

::::::{grid-item-card}
**Den deriverte av en omvendt funksjon**
^^^
* Hvis et punkt $(a, b)$ ligger på grafen til $f$, så er...
::::::
::::::::{grid}

This will produce a 2×2 grid in PDF with each card contained on a single page.

Gutter Options#

Control spacing between cards with the gutter option:

{grid} 1 1 2 2
---
gutter: 2
---

Available gutter values:

  • gutter: 1 - Small spacing (0.25rem)

  • gutter: 2 - Medium spacing (0.5rem) - Recommended

  • gutter: 3 - Large spacing (1rem)

  • gutter: 4 - Extra large spacing (1.5rem)

Card Structure#

Cards support three sections:

::::::{grid-item-card}
**Card Title**
^^^
Card body content goes here.
This is the main content area.
+++
Card footer (optional)
::::::

Where:

  • Everything before ^^^ is the header

  • Content between ^^^ and +++ (or end) is the body

  • Content after +++ is the footer (optional)

Best Practices#

1. Keep Cards Concise#

  • Each card should be self-contained

  • Aim for content that fits on one page

  • Use bullet points for clarity

2. Balance Content#

  • Try to keep cards roughly equal in size

  • This prevents awkward page breaks

3. Use Appropriate Grid Sizes#

  • 2 columns (1 1 2 2): Best for most overview content

  • 3 columns (1 1 2 3): Good for short items, may be too narrow for complex math

  • 1 column (1 1 1 1): Use for detailed explanations

4. Test PDF Output#

  • Always check PDF output after making changes

  • Look for:

    • Cards split across pages

    • Overlapping content

    • Proper alignment

Troubleshooting#

Problem: Cards are breaking across pages#

Solution: The card content is too long. Options:

  1. Split content into multiple smaller cards

  2. Simplify the content

  3. Use a single-column layout for that particular content

Problem: Layout looks wrong in PDF#

Possible causes:

  1. Not using the latest CSS files

  2. Browser cache issues (clear cache and regenerate)

  3. Custom CSS overriding print styles

Solution:

# Rebuild the book
jupyter-book clean book/
jupyter-book build book/

Problem: Cards appear too wide/narrow#

Solution: Adjust the grid specification. Remember the last number controls PDF layout:

  • {grid} 1 1 2 2 = 2 columns (50% width each)

  • {grid} 1 1 2 3 = 3 columns (33% width each)

Implementation Notes#

How It Works#

The CSS uses several print-specific properties:

  1. page-break-inside: avoid - Prevents breaks within cards

  2. break-inside: avoid - Modern alternative to page-break-inside

  3. Flexbox layout - Maintains column structure in print

  4. Fixed width percentages - Ensures proper column sizing

CSS Specificity#

The print styles use !important to override default browser/Sphinx styles. This ensures consistent PDF output across different environments.

Browser Compatibility#

The CSS is compatible with:

  • Chrome/Chromium (including PDF export)

  • Firefox

  • Safari

  • Sphinx HTML to PDF converters

Building PDFs#

To generate PDFs with proper grid formatting:

# Build the HTML first
jupyter-book build book/

# Use your browser to print to PDF
# File > Print > Save as PDF

# Or use a build script if configured
./build_pdf.sh

Questions or Issues?#

If you encounter issues with grid formatting in PDF output:

  1. Verify the grid directive syntax

  2. Check the gutter spacing

  3. Review card content length

  4. Test with a simple example first

  5. Clear browser cache and rebuild

Remember: The last number in the grid specification ({grid} 1 1 2 2) determines the PDF layout!

Innhold