Study Flow Planner

📅 Study Flow Planner

A powerful visual timeline calendar plugin for Obsidian, built for students and professionals who want to plan their week at a glance.

---

📖 Table of Contents

• Overview
• Features
• Installation
• Getting Started
• User Interface
• Creating & Managing Events
• View Modes & Zoom Levels
• Study Mode
• Note Integration
• Auto-Detection from Notes
• Language Support
• Color System
• Keyboard & Mouse Interactions
• Data Persistence
• FAQ
• Contributing

---

🔭 Overview

Study Flow Planner is a visual timeline calendar that lives inside your Obsidian vault. It displays a scrollable day-by-day grid from 5:00 to 23:00, lets you create color-coded events, link them to notes, add tags, and switch into a focused Study Mode that automatically highlights academic content.

Whether you're a student organizing exam prep or a professional managing your daily schedule, Study Flow Planner gives you a Google Calendar-like experience without ever leaving Obsidian.

---

✨ Features

---

🛠 Installation

Manual Installation (recommended while not on Community Plugins)

1. Download the latest release files:

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

2. In your Obsidian vault, navigate to:

   YourVault/.obsidian/plugins/
   

3. Create a new folder called study-flow-planner and place all three files inside it:

   YourVault/
   └── .obsidian/
       └── plugins/
           └── study-flow-planner/
               ├── main.js
               ├── manifest.json
               └── styles.css
   

4. Open Obsidian → Settings → Community Plugins → Enable Study Flow Planner.

5. The calendar icon (📅) will appear in your left ribbon. Click it to open the planner.

Note: You may need to restart Obsidian or click "Reload plugins" for the plugin to appear.

Requirements

• Obsidian version 0.15.0 or higher
• Works on both desktop and mobile

---

🚀 Getting Started

Once installed and enabled, you can open Study Flow Planner in two ways:

1. Ribbon icon — click the 📅 calendar icon in the left sidebar.
2. Command palette — press Ctrl/Cmd + P and search for:
   • Open Study Flow Planner (English)
   • Abrir Study Flow Planner (Portuguese)

On first launch, the planner loads with a few sample events so you can immediately see how it looks. These will be replaced as soon as you create your own events.

---

🖥 User Interface

The planner is divided into four main areas:

┌─────────────────────────────────────────────────────────────────┐
│ TOOLBAR: Title | Navigation | Zoom Buttons | Study Mode | + New │
├──────────┬──────────────────────────────────────────────────────┤
│          │  DAY HEADERS (Mon 1, Tue 2, Wed 3...)                │
│  GUTTER  ├──────────────────────────────────────────────────────┤
│  (time   │  ALL-DAY ROW                                         │
│  labels) ├──────────────────────────────────────────────────────┤
│  05:00   │                                                      │
│  05:30   │          TIME GRID (scrollable)                      │
│  06:00   │          Events appear as colored blocks here        │
│  ...     │          Red "now" line on today's column            │
│  23:00   │                                                      │
└──────────┴──────────────────────────────────────────────────────┘

Toolbar Elements

Gutter (Left Column)

The left column shows time labels in 30-minute slots from 05:00 to 23:00. It scrolls in sync with the main grid. Full-hour labels are displayed in a bolder style for quick visual scanning.

Day Headers

Each column header shows:

• Month abbreviation (e.g. Apr)
• Day of the week (e.g. Mon)
• Day number — today's number is highlighted with a colored circle

Weekend columns (Saturday and Sunday) have their day name and number displayed in red to stand out.

All-Day Row

A thin row below the day headers is reserved for all-day events. Click any cell in this row to quickly create an all-day event for that date.

Time Grid

The main scrollable area. Each column is one day. Each row is a 30-minute slot. The full-hour boundaries have a slightly stronger line. Events appear as colored blocks sized proportionally to their duration.

---

📝 Creating & Managing Events

Creating a New Event

There are three ways to open the creation form:

1. Click any time slot in the grid → opens the modal pre-filled with that date and time.
2. Click a day header → opens the modal pre-filled with that date as an all-day event.
3. Click + New in the toolbar → opens a blank modal defaulting to today at 09:00.

The Event Form

Editing an Event

Click any event block in the grid to open the edit modal. It works exactly like the creation form, but also shows:

• A Done checkbox to mark the event as completed (appears with strikethrough style on the grid).
• A Delete button (red) to permanently remove the event.

Deleting an Event

Open the event's edit modal and click the red Delete button at the bottom left. The action is immediate — there is no confirmation dialog.

Marking as Done

Open the event's edit modal, check the Done checkbox, and click Save. The event block will appear faded with a strikethrough title on the grid.

---

🔭 View Modes & Zoom Levels

The zoom buttons in the toolbar control how many days are visible at once:

Navigation

• Click ‹ to go back one period.
• Click › to go forward one period.
• The navigation arrows are hidden in Today/1-day view (always shows the current day).
• The period label at the top updates automatically to reflect the visible date range.

---

🎓 Study Mode

Study Mode is a special display layer designed for students. Toggle it with the 🎓 Study Mode button in the toolbar. Its state is remembered between sessions.

What Study Mode Does

When enabled:

1. Highlights study-related events with subject-specific colors — automatically, based on keywords in the event title.
2. Note-sourced events (auto-detected from daily notes) also receive subject colors when Study Mode is active.
3. User-created events that are not study-related are displayed normally.

Subject Color Map

Study Mode detects the subject from the event title and assigns a color:

Study Keywords Detected

Study Mode recognizes the following words (case-insensitive) in event titles:

study, revision, review, biology, chemistry, physics, math, mathematics, english, history, geography, science, literature, grammar, vocabulary, exercise, practice, homework, reading, lecture, exam, test, quiz, class, estudo, estudar, revisão, biologia, química, física, matemática, inglês, história, geografia, ciência, literatura, gramática, vocabulário, exercício, prática, tarefa, leitura, aula, prova, teste, redação, português

---

🔗 Note Integration

Linking a Note to an Event

Inside the event form, the Linked Note field accepts any file path within your vault, for example:

Studies/Biology/Cell Division.md
Daily Notes/2025-04-10.md
Projects/Thesis.md

Autocomplete: As you type in the Linked Note field, the planner searches your vault in real time and shows up to 8 matching file paths. Click a suggestion to fill the field automatically.

Open Note button: Once a path is entered, an Open Note button appears next to the field. Click it to open the linked note directly (works both inside the modal and from the tooltip).

Clicking a Note-Linked Event

Clicking an event that has a source note (auto-detected from a daily note) opens the corresponding note in Obsidian. These events are read-only — they cannot be edited through the planner.

---

📄 Auto-Detection from Notes

Study Flow Planner automatically reads events from your daily notes — no manual import needed.

How It Works

1. The plugin scans all Markdown files in your vault.
2. Files whose base name contains a date in YYYY-MM-DD format are parsed (e.g. 2025-04-10.md, Daily Notes/2025-04-10 Monday.md).
3. Any line matching the pattern HH:MM Event title is turned into a calendar event.

Supported Line Formats

09:00 Study Biology
- 14:30 Review Chapter 5
* 11:00 Math homework
- [ ] 16:00 Gym session
- [x] 08:00 Morning reading

All of the above will generate events on the matching date.

Notes About Auto-Detected Events

• They appear with a dashed left border to distinguish them from user-created events.
• They are read-only — clicking them opens the source note, not an edit modal.
• Their color defaults to gray (#888888). In Study Mode, they receive subject-specific colors automatically.
• They are never persisted to the plugin's own data — they are always re-read live from your notes.
• The calendar updates automatically whenever a note is created, modified, renamed, or deleted.

---

🌐 Language Support

Study Flow Planner automatically detects your language from Obsidian's locale setting (or your browser/system locale).

All labels, buttons, day names, month names, and placeholder text switch to the detected language automatically. No configuration needed.

---

🎨 Color System

When creating or editing an event, you can choose from 10 preset colors:

---

🖱 Keyboard & Mouse Interactions

---

💾 Data Persistence

All user-created events are automatically saved to Obsidian's plugin data storage (data.json inside the plugin folder). You do not need to manually save anything.

What is saved:

• All user-created events (title, date, times, color, notes, tags, linked note, done state)
• Study Mode on/off state

What is NOT saved:

• Note-detected events (always re-read live from your vault files)

Events persist across Obsidian restarts and vault reopens.

---

❓ FAQ

Q: Can I create recurring events? A: Not currently. Each event is a single occurrence. For recurring items, the best workaround is to use the auto-detection feature by writing time-stamped entries in your daily notes.

Q: Can I resize or drag events? A: Not in this version. To change the time of an event, click it to open the edit modal and update the start/end times manually.

Q: The all-day row is separate from the time grid — why? A: All-day events (like holidays or deadlines) don't have a meaningful start/end time, so they are shown in a dedicated row at the top, similar to Google Calendar's behavior.

Q: My daily note events aren't showing up — what's wrong? A: Make sure the file name includes a date in YYYY-MM-DD format anywhere in the base name. Also ensure the time entries follow the format HH:MM Event title at the start of the line (optional list markers - , * , or checkboxes - [ ] are supported).

Q: Can I use the plugin in Portuguese and English simultaneously? A: The plugin uses a single language, auto-detected from your system locale. It is not possible to mix languages in the same session.

Q: Does the plugin sync with Google Calendar or any external calendar? A: No. Study Flow Planner is self-contained within your Obsidian vault. There is no external sync.

Q: Is my data stored in the cloud? A: No. All data is stored locally inside your vault's .obsidian/plugins/study-flow-planner/data.json file.

---

🤝 Contributing

Contributions are welcome! Feel free to open issues for bug reports or feature requests, and pull requests for improvements.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

---

📄 License

MIT License — see LICENSE for details.

---