Home Pages

A modern, modular, and responsive homepage dashboard plugin for Obsidian. Built on a flexible 12-column adaptive grid, it empowers you to customize your workspace with draggable, resizable, and individually configurable widgets. Support multiple pages and third-party plugin integrations.

• Website: peyote.info
• Current release: v0.3.1
• Minimum Obsidian version: 1.7.2
• Supported platforms: Desktop and Obsidian Mobile (iOS / Android)
• License: GNU General Public License v3.0

[!NOTE] Local-First & Privacy Assured: Home Pages operates entirely within your local Obsidian vault. Layouts, states, and settings are persisted locally in data.json without any background analytics, telemetry, or hidden network tracking.

🌟 Features

🧩 Rich Built-in Dashboard Widgets

Home Pages comes with 12+ built-in productivity widgets that can be freely combined and configured:

📐 Responsive 12-Column Layout

• 12-Column Adaptive Grid: Automatically reflows and scales proportionately based on viewport width, providing a native visual layout on both desktop ultrawide monitors and mobile devices.
• WYSIWYG Layout Editing:
  • Click Edit Layout in the header to enter arrangement mode.
  • Drag cards with a mouse, or drag their title/grip on touchscreens. Insertion markers support rows, columns, and gaps; dragging near the view edge scrolls automatically. Press Esc to cancel.
  • Drag the corner handle to resize; width snaps to columns and height to rows, with a live size badge (height only on narrow screens, Esc cancels). Footer buttons and arrow keys on the focused handle step the size too. Edit mode shows 12 column guides.
  • Easily move forward, move backward, duplicate, or delete any widget.
• Multi-Page Management:
  • Click + at the end of the tab bar at any time to create distinct pages (e.g., "Work Dashboard", "Life Log", "Project Hub").
  • Drag page tabs to reorder in edit mode. Right-click tabs to rename, move left/right, or delete pages.
• JSON Import & Export: One-click copy and paste of complete dashboard layouts for easy backup and cross-vault migration.

🔌 Host API for Plugin Developers

Home Pages exposes a lightweight host API allowing other Obsidian plugins to register custom widgets and views into the homepage framework:

// Retrieve the API instance when Home Pages is loaded (or listen to "home-pages:ready")
const api = app.plugins.plugins["home-pages"]?.api;

// 1. Register a new widget type
const unregister = api.registerWidget(myWidgetDefinition, "my-plugin-id");

// 2. Programmatically pin a widget to the current homepage
api.pinWidget("my-widget-kind", { ref: "note-path" }, {
  title: "My Pinned View",
  w: 6,
  h: 4,
  provider: "my-plugin-id"
});

// 3. Trigger a dashboard redraw when underlying data changes
api.refresh("my-widget-kind");

// 4. Utilize consistent UI rendering helpers
api.ui.renderKpi(containerEl, { label: "Completed", value: 12 });
api.ui.renderEmpty(containerEl, { message: "No data available" });

Integration Example: Duowei Table (duowei-table-pro ≥ 1.4.0) registers duowei-view via the Host API. Users can right-click any table view tab and select "Pin to Homepage" to display live calendars, kanban boards, and progress timelines on their homepage.

🧩 User-Defined Custom Widgets (Folder-based & Hot-Reload)

Users can build custom widgets directly in JavaScript without creating separate plugins:

1. In plugin settings, navigate to "Custom Widgets".
2. Set the "Custom Widgets Folder" (e.g. _scripts/home-pages/), or click "📄 Create Demo Widget Template" to auto-generate demo-widget.js.
3. Create or edit .js files exporting a standard widget definition:

   module.exports = {
     kind: "user-clock",
     name: "Custom Clock",
     description: "Real-time clock widget",
     icon: "clock",
     accent: "#6366f1",
     defaultSize: { w: 4, h: 3 },
     defaultConfig: () => ({ greeting: "Hello" }),
     render(body, ctx) {
       body.empty();
       const el = body.createDiv();
       el.setText(`${ctx.config.greeting} · ${new Date().toLocaleTimeString()}`);
       ctx.registerInterval(() => {
         el.setText(`${ctx.config.greeting} · ${new Date().toLocaleTimeString()}`);
       }, 1000);
     }
   };
   

4. Save and it appears: The first time a new script loads, its widget is added to the current page (once per widget; editing a script after you removed its card does not add it back; turn off with Add new custom widgets automatically).
5. Live Hot-Reload: Save modifications to your .js file from Obsidian or an external editor like VS Code, and homepage cards will automatically reload and re-render instantly!

📥 Installation

Method 1: Obsidian Community Plugins (Recommended)

Once available in the official Obsidian Community Plugins directory:

1. In Obsidian, go to Settings → Community plugins.
2. Turn off Restricted mode and click Browse.
3. Search for Home Pages.
4. Click Install, then click Enable.

Method 2: Manual Installation

1. Download the latest release assets from the GitHub Releases page:
   • main.js
   • manifest.json
   • styles.css
2. Locate or create your plugin folder inside your vault:

   <vault>/.obsidian/plugins/home-pages/
   

3. Copy the downloaded files into that directory.
4. Reload Obsidian and enable Home Pages in Settings → Community plugins.

🖊️ Usage

1. Opening Home Pages:
   • Click the homepage icon on the left ribbon.
   • Or press Ctrl/Cmd + P and execute the command Home Pages: Open Homepage.
2. Customizing Layout & Widgets:
   • Click Edit Layout in the top-right corner of the view.
   • Click Add Widget at the top to select and insert any widget.
   • Click the Gear icon on any card header to customize its parameters (weather city, habit list, stats filters, etc.).
3. Global Settings:
   • Navigate to Obsidian Settings → Home Pages.
   • Configure auto-open on startup, default row height (px), grid gap, maximum width, and manage pages.

⚙️ Settings Reference

🔒 Data & Privacy

• 100% Local Storage: All dashboard configurations, layout JSONs, pomodoro records, and habits are stored locally in data.json.
• Zero Telemetry: The plugin does not collect usage analytics, telemetry, or user metrics.
• Network Requests: Weather queries are only initiated when a weather-enabled banner is rendered:
  • CMA Station requests public endpoints without keys.
  • Open-Meteo and QWeather only connect when explicitly selected and configured.
• Bundle Integrity: A fail-closed security gate (scripts/verify-bundle.mjs) ensures the distributed bundle contains no dynamic script generation, eval(), or new Function().

❓ FAQ

Will layout break on mobile devices?

No. Home Pages provides responsive adaptive rules for small screens. On narrow viewports, the grid seamlessly collapses into full-width or compact columns optimized for touch interaction.

Does the Pomodoro timer keep running if I switch notes or restart Obsidian?

Yes. The timer state and start timestamp are persisted in plugin memory and data. Switching views or restarting Obsidian restores the timer seamlessly.

How do I restore the default initial layout?

In Settings → Home Pages → Pages, click ＋ New Default Page at any time to generate a clean instance of the default layout.

🧑‍💻 Development

Contributions and pull requests are welcome!

# 1. Install dependencies
npm install

# 2. Start dev build with watch mode
npm run dev

# 3. Lint source code
npm run lint

# 4. Production build with security audit
npm run build

📋 Release Notes

For detailed changelogs and version release histories, see RELEASE_NOTES.md (or RELEASE_NOTES.zh-CN.md).

🤝 Support & Feedback

• Bug Reports & Feature Requests — this repository's issue tracker. Please include your Obsidian version, operating system, and reproduction steps whenever possible.
• Questions & Discussion — QQ group 1094620986. The group communicates primarily in Simplified Chinese.
• Email — [email protected]. Use email for private reproduction files or inquiries.
• Official Website — peyote.info.

📬 Contact

• QQ group: 1094620986
• Email: [email protected]
• Website: peyote.info

📄 License

This project is licensed under the GNU General Public License v3.0.