Live Preview

Generating a PDF every time you change a color or move an element is slow. This page shows a faster workflow: start pyplanner in watch mode and let it regenerate the HTML and reload the browser automatically each time you save a file.

Key topics

  • Starting the live-reload server with --watch.

  • The edit - save - reload loop.

  • Troubleshooting common issues.

Start the live-reload server

From the repository root run:

pyplanner planners/demo --watch

pyplanner generates demo.html, starts a local server and prints the address:

Serving on http://127.0.0.1:5500
Ctrl+C to exit

Open that URL in any browser. The page shows the fully rendered planner with all background images, fonts and stylesheets loaded correctly.

The edit - save - reload loop

With the server running your workflow looks like this:

  1. Edit the template planners/demo/demo.html or any asset (CSS, images) in any editor you like.

  2. Save the file.

  3. View - pyplanner detects the change, regenerates the HTML and the browser reloads automatically.

That is it. No manual re-run, no extra extensions, no specific editor required. Use the editor and browser you are most comfortable with.

Tip

Pass --verbose to see “Browser connected” and “Regenerating…” messages in the terminal so you know exactly when a rebuild happens.

Why not edit the generated file directly?

The generated HTML is a build artifact. It is overwritten every time pyplanner regenerates. Any changes you make to it will be lost. Always edit the source template.

Warning

Never edit the generated HTML file. Edit the template and save.

Troubleshooting

Images or fonts are missing in the browser

Make sure you started pyplanner from the repository root. The generated HTML references assets via {{ base }}/ which expands to the template directory path. The live-reload server serves files from the planner directory, so all assets must be reachable relative to the template.

Browser does not reload

Check that pyplanner is still running in the terminal. If it stopped (for example after an error), restart it with the same --watch command.

Browser shows Jinja2 syntax

You are opening the template file directly. Navigate to the URL printed by pyplanner (http://127.0.0.1:5500) instead.

Do and don’t summary

Do

Don’t

Run pyplanner from the repository root.

cd into the planner directory (output overwrites the template).

Open the URL printed by pyplanner.

Open the template file (it contains Jinja2 syntax the browser cannot understand).

Edit the template, then save.

Edit the generated HTML (it is overwritten on every build).

Use --watch for fast iteration.

Generate PDF every time (much slower).

Summary

You have completed the Designer Guide. Here is a recap of what you learned:

  1. Project structure - each planner in its own directory under planners/, assets alongside the template.

  2. Template basics - the .page div, asset paths, background images.

  3. Jinja2 variables - {{ }}, %% set, dot notation, filters, comments.

  4. Loops and conditionals - for/endfor, if/endif, is none, the loop variable.

  5. Macros - reusable blocks with macro/endmacro.

  6. Data reference - calendar, Year, Month, Day, WeekDay and all their properties.

  7. Template parameters - declaring typed parameters in params.xml and overriding them with -D from the command line.

  8. Assets - path rules, CSS patterns, custom fonts.

  9. Live preview - pyplanner --watch for fast iteration with any editor and browser.

Try changing colors, fonts or layouts in the Demo Planner. When you are comfortable, create your own template from scratch.

Happy designing!