Skip to content

Export Command Examples

Practical examples for using nbctl export to convert notebooks.

Basic Export

Export to HTML

nbctl export analysis.ipynb -f html

Result: analysis.html created.

Export to PDF

nbctl export report.ipynb -f pdf

Requires: LaTeX installation.

Export to Python

nbctl export notebook.ipynb -f py

Result: notebook.py with markdown as comments.

Export to Markdown

nbctl export notebook.ipynb -f md

Multiple Formats

Export to Multiple Formats

nbctl export analysis.ipynb -f html,pdf,py,md

Creates: - analysis.html - analysis.pdf - analysis.py - analysis.md

Reports Package

Export complete report package:

nbctl export quarterly_report.ipynb -f html,pdf --output-dir reports/q4/

Export Options

Without Input Cells

Create output-only report (for non-technical audiences):

nbctl export report.ipynb -f html --no-input

Result: HTML with only outputs and markdown (no code).

Without Prompts

Clean export without In[1]: / Out[1]::

nbctl export notebook.ipynb -f html --no-prompt

Combined Options

nbctl export presentation.ipynb -f html --no-input --no-prompt

Perfect for stakeholder presentations.

Workflow Examples

Generate Reports

Automated report generation:

#!/bin/bash
# generate-reports.sh

# 1. Run notebook to update outputs
nbctl run analysis.ipynb --save-output ./executed/

# 2. Export executed notebook
nbctl export ./executed/analysis.ipynb -f html,pdf --output-dir ./reports/

# 3. Share reports
echo "Reports generated in ./reports/"

Weekly Report Automation

#!/bin/bash
# weekly-report.sh

date=$(date +%Y-%m-%d)
report_dir="reports/week-$date"

mkdir -p "$report_dir"

for nb in analysis/*.ipynb; do
    name=$(basename "$nb" .ipynb)
    nbctl export "$nb" -f html,pdf --output-dir "$report_dir/"
done

echo "Weekly reports generated in $report_dir"

Documentation Generation

Generate docs from notebooks:

#!/bin/bash
# Generate markdown docs from notebooks

mkdir -p docs/tutorials

for nb in tutorials/*.ipynb; do
    nbctl export "$nb" -f md --output-dir docs/tutorials/
done

echo "Documentation generated"

Presentation Examples

Create Slides

nbctl export presentation.ipynb -f slides

Result: presentation.html (Reveal.js slides).

Presentation Package

# Create full presentation package
nbctl export talk.ipynb -f slides,pdf --no-prompt

Batch Export

Export All Notebooks

for nb in *.ipynb; do
    nbctl export "$nb" -f html
done

Export by Category

# Export analysis notebooks to HTML
for nb in analysis_*.ipynb; do
    nbctl export "$nb" -f html --output-dir html/
done

# Export model notebooks to Python
for nb in model_*.ipynb; do
    nbctl export "$nb" -f py --output-dir python/
done

Advanced Examples

Conditional Export

Export only if newer than existing HTML:

nb="analysis.ipynb"
html="analysis.html"

if [ "$nb" -nt "$html" ]; then
    nbctl export "$nb" -f html
    echo "Updated $html"
else
    echo "$html is up to date"
fi

Export with Post-Processing

# Export and customize
nbctl export notebook.ipynb -f html

# Add custom CSS
cat custom-style.css >> notebook.html

Archive Export

Create timestamped archive:

#!/bin/bash
date=$(date +%Y%m%d-%H%M%S)
archive_dir="exports/$date"

mkdir -p "$archive_dir"

nbctl export notebook.ipynb -f html,pdf,py --output-dir "$archive_dir/"

echo "Archived to $archive_dir"

CI/CD Examples

GitHub Actions

.github/workflows/export-notebooks.yml:

name: Export Notebooks
on: [push]

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2

      - name: Install dependencies
        run: |
          pip install nbctl
          sudo apt-get install texlive-xetex

      - name: Export notebooks
        run: |
          mkdir -p exports
          for nb in *.ipynb; do
            nbctl export "$nb" -f html,pdf --output-dir exports/
          done

      - name: Upload artifacts
        uses: actions/upload-artifact@v2
        with:
          name: notebooks-export
          path: exports/

Tips & Best Practices

1. Test Exports

# Test HTML export first (fastest)
nbctl export notebook.ipynb -f html

# If OK, export to PDF
nbctl export notebook.ipynb -f pdf

2. Organize Outputs

# Organize by format
nbctl export notebook.ipynb -f html --output-dir html/
nbctl export notebook.ipynb -f pdf --output-dir pdf/
nbctl export notebook.ipynb -f py --output-dir python/

3. Clean Before Export

# Clean and run before export
nbctl clean notebook.ipynb
nbctl run notebook.ipynb
nbctl export notebook.ipynb -f html,pdf

Troubleshooting

PDF Export Fails

Install LaTeX:

# macOS
brew install --cask mactex

# Ubuntu
sudo apt-get install texlive-xetex texlive-fonts-recommended