Getting Started

Get Social Archiver up and running in just a few minutes.

Prerequisites

• Obsidian Desktop for plugins
• Internet connection for archiving
• Email address for authentication

Installation

Community Plugins (Recommended)

Note: Social Archiver is currently under review for the Obsidian Community Plugin store. Once approved, you'll be able to install it directly through the plugin browser. In the meantime, please use one of the manual installation methods below.

Manual Installation

Option 1: BRAT Plugin (Recommended - Auto Updates)

Using BRAT (Beta Reviewers Auto-update Tool) allows you to receive automatic updates:

1. Install BRAT (if not already installed)

   • Open Settings → Community Plugins → Browse
   • Search for "BRAT"
   • Install and enable it

2. Add Social Archiver via BRAT

   • Open Settings → BRAT
   • Click Add Beta Plugin
   • Enter repository: https://github.com/hyungyunlim/obsidian-social-archiver-releases
   • Click Add Plugin

3. Enable the plugin

   • Go to Settings → Community Plugins
   • Find "Social Archiver" and enable it

BRAT will automatically check for and install updates from new releases.

Option 2: Manual Download

For one-time installation without auto-updates:

1. Download latest release from GitHub Releases
2. Extract main.js, manifest.json, and styles.css
3. Copy to .obsidian/plugins/social-archiver/ in your vault
4. Reload Obsidian (Cmd/Ctrl + R)
5. Enable in Settings → Community Plugins

Initial Setup

1. Account Authentication

First-time setup requires email verification:

1. Open Plugin Settings

   • Click ribbon icon (bookmark-plus) - it will prompt you to open settings
   • Or go to Settings → Social Archiver

2. Enter Email & Username

   • Email: For authentication only (magic link will be sent here)
   • Username: Your unique public identifier

   Choose Username Carefully

   Your username cannot be changed later. It will be part of your public timeline URL (/{username}), so choose wisely!

3. Check Email for Magic Link

   • Check your inbox for verification email
   • Not receiving email? Check your spam/junk folder
   • The link is valid for 5 minutes

4. Click Magic Link

   • Opens a verification page in your browser
   • Shows "Authentication Successful" with your username
   • Click "Open in Obsidian" button

5. Complete Setup

   • Obsidian opens automatically via deep link (obsidian://social-archive?token=...)
   • Authentication completes in the background
   • You're ready to archive!

Why do I need an account?

Social Archiver uses server infrastructure to fetch social media content through web scraping. Account authentication helps prevent abuse from bots and automated scripts.

Authentication Details:

• Passwordless: We use magic links sent to your email - no passwords to remember
• Email-based: Simple, secure authentication
• Multi-device: If you use Obsidian on multiple devices, you'll need to log in on each device separately - authentication state doesn't sync across devices

2. Configure Settings (Optional)

Fine-tune your archive preferences:

# Settings → Social Archiver

Archive Folder: Social Archives/{platform}/{year}/{month}/
Media Folder: attachments/social-archives/
Download Mode: images-and-videos  # or text-only, images-only

Your First Archive

Desktop Workflow

Method 1: Archive Modal (Recommended)

1. Click the ribbon icon (bookmark-plus) in the left sidebar
   • Or click the archive button at the top of Timeline View
2. Archive Modal opens
3. Paste social media post URL
4. Platform is automatically detected (e.g., Facebook, Instagram, X)
5. Configure options:
   • Download media: Text only, Images only, or Images and videos
   • YouTube options: Include transcript, formatted transcript
   • My Notes (optional): Add personal comments or tags
6. Click Archive button

Method 2: Post Composer in Timeline View

1. Open Timeline View (calendar-clock ribbon icon)
2. Click the Post Composer at the top (text input area)
3. Write your content in the editor
4. Paste social media URL(s) in your content
5. Optionally attach images
6. Click Post button to publish to your vault
7. Archive suggestion banner appears on the post card
8. Click "Archive this post" to save the linked social media content

Which Method to Use?

• Archive Modal: Best for directly archiving social media posts without adding commentary
• Post Composer: Best for curating posts with your own thoughts, then archiving the linked content

Example: Archiving a Tweet

Using Archive Modal:

1. Copy URL: https://twitter.com/obsidmd/status/123456789
2. Click ribbon icon (bookmark-plus) to open Archive Modal
3. Paste URL in input field
4. Platform detected: "X (Twitter)"
5. Select download mode: "Images and videos"
6. Click "Archive" button
7. Document created immediately in your vault
8. Background job fetches full content
9. Real-time notification when complete

What Happens Next

After clicking "Archive":

1. Instant Note Creation: A note appears immediately in your vault with basic info
2. Background Download: The full post content downloads in the background - you can close Obsidian or continue working
3. Live Progress Updates: You'll see real-time notifications as it downloads
4. Automatic Retry: If something fails, it automatically tries again (up to 3 times)
5. Final Result: When complete, all images, videos, and text are saved in your note

You Don't Need to Wait

The note is created instantly. The download happens in the background, so you can keep working or even close Obsidian! Most archives complete in seconds, but some posts with lots of media may take a few minutes.

Example Output

Archived posts look like this:

---
platform: facebook
author: John Doe
authorUrl: https://www.facebook.com/johndoe
published: "2024-11-14 10:30"
archived: "2024-11-14 15:22"
archive: false
tags:
  - social/facebook
originalUrl: https://www.facebook.com/share/p/ABC123/
likes: 127
comments: 8
shares: 15
share: true
shareUrl: https://social-archive.org/username/abc123
---

Just finished reading an amazing book on productivity!
Here are my top 3 takeaways that completely changed how I work...

The most important lesson was about deep work and focusing on
one thing at a time instead of multitasking.

Highly recommend this to anyone looking to improve their workflow!

---

![image 1](attachments/social-archives/2024-11-14-facebook-1234567890/1.jpg)

---

**Platform:** Facebook | **Author:** [John Doe](https://www.facebook.com/johndoe)
**Published:** 2024-11-14 10:30 | **Likes:** 127 | **Comments:** 8 | **Shares:** 15

**Original URL:** https://www.facebook.com/share/p/ABC123/

Next Steps

• Explore Timeline View
• Learn about Web Sharing
• Create Your Own Posts

Important

Only archive content you have permission to save. Respect copyright laws and platform terms of service.

Need Help?

• GitHub Issues
• Documentation

Happy archiving!