coursebook

Version
Status
Documentation
Tools
Compatibility
Stats

What is coursebook?

coursebook turns a folder of markdown files into the materials for a course or publication: a Word, PDF, or HTML document with the text, a PowerPoint deck with accompanying slides, and a document of teaching notes. You write each part of your project once, in plain markdown, with its text, slides, and notes side by side. A short project file sets the order of the parts and how the results should look.

Why use coursebook?

• One source for everything: the text, slides, and notes for each chapter or section live in the same markdown file, so they stay in sync.
• Outlines you already know: the structure of a project is a traditional outline (I, A, 1, a, i). Headings and their levels come from it.
• Microsoft Office output: Word and PowerPoint files are styled with templates, including Word (.docx, .dotx) and PowerPoint (.pptx, .potx) templates and Office themes (.thmx).
• PDF and HTML too: the text and notes can also be exported to PDF (without LaTeX) and to a single, self-contained HTML file, at the same time as Word.
• Academic features: footnotes, citations from BibTeX or other bibliography files (with Bluebook citations for law reviews), tables, math, and images, all through pandoc.
• Styles for academic work: built-in styles for coursebooks, books, and law review articles, and an easy way to add your own.
• Nothing else to install: a copy of pandoc is included.

coursebook is not a word processor. If you need tracked changes or comments from co-authors, export with coursebook and continue in Word.

Getting started

Requirements

coursebook requires Python 3.11 or later and runs on Linux, macOS, and Windows. Any text editor works for writing the markdown files.

Installation

To install coursebook, use pip:

pip install coursebook

PDF export needs one more package, which this installs:

pip install "coursebook[pdf]"

Usage

Starting a project

coursebook new creates a project folder with a project file, a source file for each outline entry, and a "visuals" folder:

coursebook new my_course --style coursebook --entry "I: Introduction" --entry "II: Negligence"

Instead of --entry, you can pass --outline outline.txt, a text file with one outline line per line. Use --format toml or --format yaml for a toml or yaml project file. Without an outline, a short sample outline is used. Existing source files are never overwritten.

Project folders

A project is a folder with a project file, one markdown file for each entry in the outline, and (optionally) a "visuals" folder with images:

my_course/
├── project.ini
├── introduction.md
├── literature_review.md
├── ...
└── visuals/
    └── chart.png

The project file

The project file is named "project" and may be an ini, toml, or yaml file. Its "Project" section holds settings and its "Outline" section holds the structure of the project:

[Project]
Name: Crazy Idea
Author: Corey Rayburn Yung
Style: coursebook
Include: text, slides, notes
Slides Template: chalkboard
Output Folder: output

[Outline]
I: Introduction
II: Literature Review
III: My Cool Idea
A: Interesting Premise 1
1: Underlying Facts
2: Supporting Work
B: Interesting Premise 2
IV: Conclusion

The level of each outline entry comes from its label: upper case Roman numerals (I), upper case letters (A), numbers (1), lower case letters (a), and lower case Roman numerals (i), in whatever order you nest them. A book can number its chapters with "1", "2", and so on. Labels may repeat under different parents (an "A" under "I" and another under "II"). If you skip a label (such as going from "A" to "C"), coursebook warns you but keeps going. After "h", an "i" continues the letters.

Entries without numbers, such as a preface or an appendix, use dashes as their labels: - for the top level, -- for the level below it, and so on. The numbering of the other entries continues around them:

[Outline]
-: Preface
I: Introduction
II: Argument
-: Appendix
A: Data

An entry can name its own source file after a |, which is useful for files in subfolders or for entries that share a title:

I: Introduction | chapters/intro.md
A: Overview | intro_overview.md
II: Negligence
A: Overview | negligence_overview.md

In a toml or yaml file, the outline is a list (of lines or of [label, title, file] lists):

outline = [
    "I: Introduction",
    "II: Background",
    "A: History",
    "B: Current Law"]

[project]
name = "A Modest Proposal"
style = "law review"

Settings

Setting names ignore case, spaces, and underscores ("Output Folder", "output_folder", and "OUTPUT FOLDER" are the same).

Source files

Each outline entry is matched to a markdown file named after its title, in lower case with underscores for spaces and punctuation ("Interesting Premise 1" matches "interesting_premise_1.md"). An entry without a file still gets a heading, and coursebook warns you that the file is missing.

A source file is divided into sections by lines with the section name in angle brackets. Anything before the first divider is text:

---
title: A Better Title Than the Outline's
visuals_in_notes: true
---

The text of the chapter, with a footnote.[^1]

# A Subheading

![Enrollment by year](chart.png){width=50%}

[^1]: Footnote labels only need to be unique within each file.

<slides>

# First Slide

- A point
- Another point

::: notes
Speaker notes for this slide.
:::

---

- A second slide, without a title

<notes>

Notes for the instructor's guide.

• Front matter (optional) may set title (used in place of the outline title) and visuals_in_notes.
• Text: write headings starting at #. They are placed beneath the heading for the outline entry.
• Slides: start each slide with a # heading or separate slides with ---. If the slides do not start with a heading, the first slide is titled with the outline entry. Speaker notes go in ::: notes blocks.
• Notes: like the text, but collected into a separate document. Entries without notes are left out of it.
• Images are found in the project folder and the visuals folder.
• Citations use pandoc's syntax ([@scalia1997, 23]) when the project has a bibliography. With a note style, such as the Bluebook style used by law review, each citation becomes a footnote.

Building

From the project folder, run:

coursebook

Or name the folder and choose the sections to create:

coursebook path/to/my_course --include slides --output-folder handouts

(coursebook build is the same command, and python -m coursebook works too.) For the project above, coursebook creates "crazy_idea.docx", "crazy_idea_slides.pptx", and "crazy_idea_notes.docx" in the output folder. With Text Format: word, pdf, html, it also creates "crazy_idea.pdf" and "crazy_idea.html".

When you open a Word document with a table of contents, Word asks whether to update the fields in it; answer yes to fill in the table. PDF files use the fonts installed on your computer, so a missing font (such as Georgia on some Linux systems) is replaced with another one.

Styles

A style's formatting is applied to pandoc's default Word template and passed to the PDF and HTML files. If you name your own Word template, its formatting is used for Word files instead.

Templates

A template setting may be a path (relative to the project folder) or a name without an extension. A name is looked for first in the project folder and then among the templates included with coursebook ("chalkboard"). Word accepts .docx and .dotx files, and PowerPoint accepts .pptx and .potx files and .thmx Office themes. A PowerPoint template must have the standard layouts (Title Slide, Title and Content, Section Header, Two Content, Comparison, Content with Caption, and Blank).

To start your own template from a style's, write it out, change it in Word or PowerPoint, and name it in the project file:

coursebook template "law review" house_style.docx
coursebook template coursebook lecture.pptx

Text Template: house_style
Slides Template: lecture

The CSL setting works the same way: it may be a path to a .csl file or the name of one, looked for in the project folder and then among the citation styles included with coursebook ("bluebook-law-review"). Thousands of citation styles are available from the Zotero Style Repository.

Using Python

import coursebook

project = coursebook.Project.from_folder('my_course')
print(project.missing)            # outline entries without a source file
print(project.assemble('slides')) # the combined markdown for the slides
project.build(include = ['text'])

New styles and export formats are registered when you subclass coursebook.Style or coursebook.Exporter:

import dataclasses

import coursebook


@dataclasses.dataclass
class Seminar(coursebook.Coursebook):
    number_headings: bool = True
    formatting: coursebook.Formatting = dataclasses.field(
        default_factory = lambda: coursebook.Formatting(
            body_font = 'Garamond', font_size = 12, page_numbers = True))

A project file can then use Style: seminar.

Contributing

Contributors are always welcome. Feel free to grab an issue to work on or make a suggested improvement. If you wish to contribute, please read the Contribution Guide and Code of Conduct.

Similar Projects

• quarto: a publishing system that creates documents, presentations, websites, and books from markdown and notebooks.
• pandoc: the document converter that coursebook uses to create its files.
• Typst: the typesetting system that coursebook uses to create PDF files.

Acknowledgments

I would like to thank the University of Kansas School of Law for tolerating and supporting this law professor's coding efforts, an endeavor which is well outside the typical scholarly activities in the discipline.

The included Bluebook citation style ("bluebook-law-review.csl") is from the Citation Style Language styles repository. Its authors are listed in the file, and it is licensed under the Creative Commons Attribution-ShareAlike 3.0 License.

License

Use of this repository is authorized under the Apache Software License 2.0.