Paper Flow

Paper Flow is an Obsidian plugin for paper-heavy notes. It detects paper URLs in Markdown files, resolves paper metadata, downloads open-access PDFs, refreshes citation counts, and generates Mermaid literature maps.

Features

• Watches modified Markdown files and extracts paper URLs.
• Resolves metadata from Semantic Scholar, arXiv, Crossref, OpenAlex, and citation meta tags.
• Downloads open-access PDFs when a PDF URL is available.
• Inserts a managed metadata table between paper-flow HTML comments.
• Periodically refreshes citation counts.
• Generates a Mermaid paper map for the current note.

Commands

• Paper Flow: Process paper URLs in current note
• Paper Flow: Update known paper citation counts now
• Paper Flow: Generate Mermaid paper map for current note

Supported URLs

• arXiv abstract and PDF URLs.
• DOI URLs.
• Semantic Scholar paper URLs.
• Direct PDF URLs.
• Publisher pages that expose citation_* metadata.

Privacy and Network Access

Paper Flow sends paper identifiers, paper URLs, and paper titles to public metadata services in order to resolve metadata and citation counts. The plugin currently uses:

• Semantic Scholar
• arXiv
• Crossref
• OpenAlex

The plugin does not upload your full note content. It reads Markdown files locally and extracts URLs from them.

File Changes

Paper Flow can modify Markdown notes by inserting or replacing generated blocks marked with:

• <!-- paper-flow:start -->
• <!-- paper-flow:end -->
• <!-- paper-flow-map:start -->
• <!-- paper-flow-map:end -->

Downloaded PDFs are saved inside your vault. The default folder is papers/.

Development

Install dependencies:

npm install

Run type checks:

npm run typecheck

Build the plugin:

npm run build

For an Obsidian community release, attach these files to the GitHub release:

• main.js
• manifest.json
• styles.css

The GitHub release tag must match the version field in manifest.json.

Notes

• Citation counts prefer Semantic Scholar. If Semantic Scholar is rate limited, OpenAlex and Crossref are used as fallbacks.
• Precise paper-to-paper arrows require reference data from Semantic Scholar. When that is unavailable, the map falls back to chronological "later development" arrows.
• A Semantic Scholar API key is optional but recommended for stable citation updates and graph generation.