eoas-ubc/paged_html_theme

A sphinx theme using pagedjs and myst_nb

PagedJS HTML Sphinx Theme

Background

This theme provides a Sphinx template that uses the pagedjs Javascript library to implement a few of the forthcoming CSS3 paged media directives for pdf pagination and headers/footers. It is based on the pandoc template for rstudio/pagedown.

It was created by Mara Colclough as part of the EOAS/UBC courseware project

Demonstration

An example build:

• The original myst markdown

Formatted with page-breaks, page numbers and header information from the file headers.json

• The rendered html

Installation

pip install git+https://github.com/eoas-ubc/paged_html_theme.git@master --upgrade

• or if you want to install the version you just cloned, do an editable install

  pip install -e . --upgrade
  

Build the example

• clone the repository and cd to the directory

  git clone https://github.com/eoas-ubc/paged_html_theme.git
  cd paged_html_theme
  

• execute build_page to build the example

build_page examples/page_break_test/test_file.md  \
  examples/page_break_test/headers.json 

• this will write:

  examples/page_break_test/_test_file_build/test_file.html

• Edit headers.json to change headers.

• if headers.json is missing from the command line and doesn't exist, a default version will be created

• build_page --help prints the docstring

Development

• The print-specfic styling can be change by injecting new css styles into src/paged_html_theme/layout.html

• To modify the @media print css

  1. create the environment and activate

  cd paged_html_theme
  conda  env create --name theme_dev --file environment.yml
  conda activate theme_dev
  

  1. pip install in editable mode:

  pip install -e . --upgrade

  1. edit src/scss/print_style.scss

  2. use inject_css to build print_style.css and inject into src/paged_hytml_theme/layout.html

  cd paged_html_theme
  inject_css
  ``
  
  1. Reinstall
  
    `pip install . --upgrade`
  
  
  

Adjustable parameters/features

• To insert a pagebreak, use <div class="page-break"></div>

• To change the page size, or the left and center header edit headers.json

Next steps/notes

1. Make parameter setup compatible with the latex pdf builder via issue 201

2. Add bookmarks once chrome implements 781797