Netlify Status Downloads

Paperead A tiny tool to present and manage your reading and notes.


Use pip:

pip install paperead

Or use pipx:

# Install pipx
pip install --user pipx
pipx ensurepath

# Install Schemdule
pipx install paperead

# Upgrade
pipx upgrade paperead


Command-line Management

Create/Delete/List materials and notes.

# Use current directory as data directory
paperead new/rm/list --help

# Custom data directory
paperead -D "path/to/dataDir" <COMMANDS>

Website Server

paperead serve

paperead -D "path/to/dataDir" serve

Then visit http://localhost:3649.


  • /api/materials/
    • GET (index.json): Get all ids for materials
    • POST: Create or update a material
  • /api/materials/<id>/
    • GET (index.json): Get data of the material
    • DELETE: Delete the material
  • /api/materials/<id>/assets/<path>
    • GET: Access assets of the material
  • /api/materials/<id>/notes/
    • GET (index.json): Get all ids for notes of the material
    • POST: Create or update a note of the material
  • /api/materials/<id>/notes/<nid>/
    • GET (index.json): Get data of the note of the material
    • DELETE: Delete the note of the material

Paperead can also build a static website.

paperead build

The built website will be at ./dist, which can be hosted in any static HTTP server.

Before building, existed dist directory will be deleted. So DO NOT make your files in dist directory.

If you want a simple local server, use -P option.
Paperead will generate a python script in the dist directory to serve the static website.
The script has no third-party dependencies. Only Python standard library is needed.

paperead build -P

cd dist

Data Directory

Paperead works in a data directory. The directory’s structure is like the following.


Material Description

<material>/ contains the metadata and the description for the material.

# Metadata in YAML
name: Name
creation: 2021-09-26 09:00:00+00:00
modification: 2021-09-26 09:00:00+00:00
  image: "./assets/image.png"
- tag1
- tag2
  key1: "value1"
  key2: "value2"

Description in Markdown.


<material>/notes/<note>.md contains the metadata (the structure is as same as material’s description) and the content for the note for the material.

  • Do NOT use space in note ID.


<material>/assets/ contains all additional files for the material, this will be directly served as static files,
and all .md files for the material can access these files by using ./assets/... or ../assets/... (just relative path).


paperead.ini contains configuration. If it is not existed, default configuration will be used.

port = 3649
dist = ./dist


# Run backend

cd src/main
python -m paperead -D "path/to/dataDir" serve
# endpoint: http://localhost:3649/api

# Run frontend
cd src/web
npm run dev
# endpoint: http://localhost:3000