Paperead

Netlify Status Downloads

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

Install

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

Usage

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.

RESTful APIs:

  • /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 serve.py 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
python serve.py

Data Directory

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

/
  paperead.ini  
  material1/
    description.md
    assets/
    notes/
      note1.md

Material Description

<material>/description.md 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
targets:
  image: "./assets/image.png"
tags:
- tag1
- tag2
extra:
  key1: "value1"
  key2: "value2"
---

Description in Markdown.

Notes

<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.

Assets

<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).

Configuration

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

[server]
port = 3649
dist = ./dist

Development

# 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

GitHub

https://github.com/StardustDL/paperead