paperead 0.0.4

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

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

• Platform
• Python
• Document

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