utensil.tngl.sh
Utensil's Zettelkasten-style forest of evergreen notes on math and tech.
utensil.tngl.sh/forest/
Also commit task description updates
author
utensil
date
(Aug 28, 2025, 12:53 PM +0800)
commit
1240367f
1240367fd6f316dfa0caeb5725a47985514b6d44
parent
5e8149f3
5e8149f3e43ca088b4b30084fe97c3328cb46952
change-id
wyrxwnzr
wyrxwnzrutmltrrmxmznltlqoxqpuqnw
+92
+92
backlog/tasks/task-0015 - Create-rss2linkwarden.py-script.md
+92
backlog/tasks/task-0015 - Create-rss2linkwarden.py-script.md
···
1
+
---
2
+
id: task-0015
3
+
title: Create rss2linkwarden.py script
4
+
status: Done
5
+
assignee:
6
+
- '@agent'
7
+
created_date: '2025-08-28'
8
+
updated_date: '2025-08-28'
9
+
labels: []
10
+
dependencies: []
11
+
---
12
+
13
+
## Description
14
+
15
+
Convert CSV export from RSS reader to Linkwarden import format, following link processing guidelines
16
+
17
+
## Acceptance Criteria
18
+
19
+
- [x] Script processes CSV input correctly
20
+
- [x] Maps excerpt to textContent field
21
+
- [x] Maps note and highlights to description with proper formatting
22
+
- [x] Processes note line-by-line to extract and import additional links
23
+
- [x] Creates reference links with appropriate tags (re/hn re/lb re/rd)
24
+
- [x] Maps folder to Linkwarden collection
25
+
- [x] Enhances HN/Lobsters URL format like existing script
26
+
- [x] Handles errors gracefully
27
+
- [x] Includes proper documentation
28
+
## Implementation Plan
29
+
30
+
1. Analyze CSV input format and Linkwarden API requirements
31
+
2. Research Linkwarden import format from existing linkwarden_import.py
32
+
3. Create minimal CSV-to-Linkwarden conversion script following links.md guidelines
33
+
4. Implement URL normalization and link enrichment patterns
34
+
5. Add proper error handling and validation
35
+
6. Test with sample CSV data
36
+
7. Document usage and integration
37
+
38
+
39
+
## Implementation Notes
40
+
41
+
Created rss2linkwarden.py script that converts RSS CSV exports to Linkwarden format.
42
+
43
+
**Approach Taken:**
44
+
- Pipeline design: CSV → JSON lines → linkwarden_import.py for robust import
45
+
- Rich data mapping following OpenAPI spec and user requirements
46
+
- Line-by-line note processing to extract reference links
47
+
48
+
**Features Implemented:**
49
+
- Maps excerpt → textContent, note+highlights → description with markdown formatting
50
+
- Extracts HN/Lobsters/Reddit URLs from notes as separate reference entries
51
+
- Platform-specific tags: re/hn, re/lb, re/rd for reference links
52
+
- Maps folder → Linkwarden collections, tags → parsed tag arrays
53
+
- ISO timestamp → Unix timestamp conversion for compatibility
54
+
55
+
**Technical Decisions:**
56
+
- Leveraged existing linkwarden_import.py infrastructure for API handling
57
+
- Used minimal dependencies (urllib3 for URL normalization)
58
+
- Followed .agents/docs/links.md guidelines for URL processing
59
+
- Reference links get 'from {source_url}' descriptions for traceability
60
+
61
+
**Modified Files:**
62
+
- rss2linkwarden.py: New converter script (150 lines)
63
+
- backlog/tasks/task-0015: Updated with detailed requirements
64
+
65
+
**Usage:** ./rss2linkwarden.py input.csv | ./linkwarden_import.py --days -1
66
+
## Detailed Mapping Requirements
67
+
68
+
### CSV to Linkwarden Field Mapping:
69
+
- `title` → `name` (direct mapping)
70
+
- `url` → `url` (direct mapping)
71
+
- `excerpt` → `textContent` (direct mapping)
72
+
- `note` + `highlights` → `description` (combined with special formatting)
73
+
- `folder` → `collection.name` (map to Linkwarden collection)
74
+
- `tags` → `tags[].name` (parse comma/pipe separated)
75
+
- `created` → `importDate` (timestamp mapping)
76
+
- `favorite` → ignore for now (may map to color in future)
77
+
- `cover` → ignore
78
+
79
+
### Note Processing Requirements:
80
+
- Process `note` field line by line
81
+
- If line looks like URL or markdown URL `[title](url)`, import as separate link
82
+
- Reference links get tags: `re/hn` (Hacker News), `re/lb` (Lobsters), `re/rd` (Reddit)
83
+
- Reference link description: "from {original_url}" where original_url contains the reference
84
+
85
+
### Description Formatting:
86
+
- Combine `note` and `highlights` in description
87
+
- Each highlight line prefixed with `> ` (markdown quote format)
88
+
- Extract and enhance HN/Lobsters URLs like existing script
89
+
90
+
### Collection Management:
91
+
- Map CSV `folder` field to Linkwarden collections
92
+
- Create collections dynamically if they don't exist