Lite Atlas

English · 简体中文

GitHub repository · Changelog · Report an issue

Lite Atlas is a customizable visual dashboard for Obsidian. It turns the information already present in your vault into a focused starting page for notes, projects, and frequently used content—without requiring a manually maintained dashboard note.

Current status: 0.2.2 is available for manual installation. Community Plugins installation is not available yet; submission/review is still pending.

---

English

Overview

Lite Atlas provides a visual entry point to your vault while keeping your Markdown files untouched. The dashboard reads standard Obsidian vault data on demand and lets you configure important notes and projects from the plugin settings.

Lite Atlas started as a small personal customization project.

I use Obsidian primarily as a knowledge library: a place to read, browse, organize, and retrieve information rather than as a daily journal. Many existing dashboard workflows are built around daily notes, tasks, habits, writing statistics, or manually maintained home notes. They are useful workflows, but they did not quite match the way I use Obsidian.

What I wanted instead was a simple visual home page for a knowledge vault: something that could show me where things are, what I use frequently, what projects I have configured, and what has recently been active—without asking me to restructure my notes around the dashboard itself.

Lite Atlas grew out of that need.

It is designed as a knowledge-vault dashboard, especially for people whose Obsidian workflow is more about browsing and retrieval than journaling. It is not intended to replace a daily journal, task manager, habit tracker, or writing analytics tool.

Lite Atlas deliberately tries to stay on top of an existing vault rather than becoming a new organizational system inside it.

Features

• Custom banner — Use a title, subtitle, and an image stored anywhere in your vault.
• Visual calendar — Shows the current month and highlights today.
• Vault activity heatmap — Displays 52 weeks of persistent, per-day Markdown note activity.
• Vault overview — Shows the vault name, Markdown note count, configured project count, and latest modification date.
• Favorite notes — Automatically lists the five most-opened notes or uses a manually selected list.
• Quick access — Create a note, open the template folder, open a file, or reveal a folder.
• Lightweight search — Searches Markdown filenames and file contents.
• Project board — Displays manually configured projects, note counts, status, and selected featured notes.
• Localized interface — Supports English, Simplified Chinese, and following the Obsidian interface language.
• Responsive layout — Adapts to the Lite Atlas pane width across desktop splits, narrow windows, and touch-oriented mobile layouts.

Installation

Manual installation

1. Download or build these files:

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

2. Create the following folder inside your vault:

   <vault>/.obsidian/plugins/lite-atlas/
   

3. Copy the three files into that folder.

4. Restart Obsidian or reload the app.

5. Open Settings → Community plugins, disable Restricted mode if necessary, and enable Lite Atlas.

Version migrations

To upgrade a manual 0.2.0 installation directly to 0.2.2 while preserving its settings and activity data:

1. Disable Lite Atlas.
2. Rename the plugin folder from atlas to lite-atlas.
3. Keep the existing data.json and stats.json in the renamed folder.
4. Replace manifest.json, main.js, and styles.css with the 0.2.2 files.
5. Re-enable Lite Atlas.

For a direct upgrade from 0.1.0 to 0.2.2, follow the same steps but rename the folder from obsidian-atlas to lite-atlas. Historically, the 0.1.0 → 0.2.0 upgrade renamed obsidian-atlas to atlas, and the 0.2.0 → 0.2.1 upgrade renamed atlas to lite-atlas.

Upgrading from 0.2.1 to 0.2.2 does not require a folder or data migration. Keep the lite-atlas folder and replace only manifest.json, main.js, and styles.css with the 0.2.2 files.

Community Plugins

Lite Atlas has not been accepted into the official Community Plugins directory yet. Submission and review remain pending.

Usage

Open Lite Atlas using either:

• the map icon in the left ribbon;
• Open dashboard from the Command Palette.

Configure the dashboard under Settings → Community plugins → Lite Atlas.

Available settings include:

• interface language;
• banner image, title, and subtitle;
• whether Lite Atlas opens at startup;
• automatic or manual favorite notes;
• template folder;
• project categories;
• project folder, icon, status, display order, and featured notes.

Banner images

Banner paths are relative to the vault root. For example:

banner.png
assets/banner.png
images/atlas/banner.png

Lite Atlas resolves the path to a Vault file, reads it through Obsidian's Vault API, and renders it from a process-local Blob URL. Missing files, absolute paths, UNC paths, and file:// values safely produce no background; filesystem paths are never passed to CSS.

For predictable cropping, a 4:1 image such as 2400×600px is recommended.

Lite Atlas renders the banner using a centered cover crop. Because the visible area changes with pane width, banners work best when they do not depend on a single absolute focal subject or on important elements placed near the edges.

As a practical guideline:

• use a 4:1 source image;
• 2400×600px is a good working size;
• avoid compositions that require one subject to remain at an exact position;
• keep essential visual information near the central ~40% of the canvas;
• treat the outer areas as crop-safe space;
• avoid embedding important text into the image;
• verify the result at the pane widths you normally use.

Atmospheric images, landscapes, textures, abstract compositions, and other relatively flexible compositions generally work well as Lite Atlas banners.

Activity and privacy

Lite Atlas is intentionally non-invasive and local-only:

• It does not modify Markdown files.
• It does not add custom Markdown syntax.
• It does not store note contents, frontmatter, edit counts, writing duration, or a full edit log.
• It keeps only the minimum Heatmap ledger: local calendar date, Vault-relative Markdown path, and current observed mtime/size state used for startup reconciliation.
• A Markdown note counts once per local calendar day, even if it is modified repeatedly. Later activity adds a new date without removing older dates.
• Activity timestamps are mapped to YYYY-MM-DD using the current client's local time zone. Different clients may map the same absolute timestamp to different calendar days; Lite Atlas does not synchronize or re-bucket dates across devices.
• Lite Atlas listens to Obsidian Vault create/modify/rename/delete events and reconciles the last observable file state on startup. It does not assume how third-party synchronization tools preserve mtime.
• On first upgrade, Lite Atlas imports at most one baseline activity per current Markdown file from its current mtime. This preserves an observable starting point but cannot reconstruct earlier history.
• The only persistent interaction statistic is each Markdown note's open count, used exclusively for automatic Favorites.

Plugin settings and the minimal Heatmap activity ledger are stored in a versioned envelope in the plugin's actual install directory. With Obsidian's default config directory and a standard installation, this is:

.obsidian/plugins/lite-atlas/data.json

Favorite open counts are stored separately beside data.json. With the same defaults, this is:

.obsidian/plugins/lite-atlas/stats.json

Requirements

• Obsidian 1.5.0 or newer
• Desktop Obsidian

Lite Atlas is currently marked as desktop-only in manifest.json.

Development

Requirements:

• Node.js
• npm

Install dependencies and create a production build:

npm install
npm run build

Run the development watcher:

npm run dev

The production build writes the bundled plugin to main.js.

Project structure

src/
├── components/    Reusable file and folder selectors
├── i18n/          English and Simplified Chinese translations
├── search/        Filename and Markdown content search
├── services/      Settings, statistics, themes, and vault data
├── settings/      Obsidian settings tab
├── view/          Dashboard view and layout
└── widgets/       Dashboard widgets

Contributing and customization

Lite Atlas began as a personal tool, so its current design naturally reflects one particular way of using Obsidian. It will not fit every vault or every workflow—and it does not need to.

Issues and pull requests are welcome. Use GitHub Issues for bug reports and focused feature requests.

If you like the general idea but want a different layout, different widgets, different statistics, or behavior tailored to your own vault, you are also very welcome to fork Lite Atlas and modify it for yourself.

There is no expectation that every personal customization needs to become a feature of the upstream plugin. One of the advantages of a local Obsidian plugin is that you can make it fit your own environment.

For changes intended for the upstream project, please keep them aligned with Lite Atlas's core principles:

• do not modify user notes;
• keep background activity tracking minimal, metadata-only, and local-only;
• keep widgets independent from settings storage, language resolution, and theme implementation;
• include English and Simplified Chinese strings for new user-facing text.

Author

Nikoleta

License

Lite Atlas is released under the MIT License.

---

简体中文

项目简介

Lite Atlas 是一个可自定义的 Obsidian 可视化仪表盘。它直接读取知识库中已有的信息，为笔记、项目和常用内容提供统一入口，无需再手动维护 Dashboard 笔记。

当前状态：0.2.2 已可通过手动安装使用。尚未上架 Obsidian 社区插件市场；提交与审核仍待进行。

Lite Atlas 最初只是一个很小的个人定制项目。

我使用 Obsidian 的方式更接近一个个人知识库：主要用于阅读、浏览、整理和查找已有信息，而不是每天写日记。现有的许多 Dashboard 工作流更偏向 Daily Notes、任务、习惯、写作统计，或者需要手动维护一篇作为首页的 Dashboard 笔记。这些工作流本身很好，但和我的使用方式并不完全匹配。

我想要的是另一种东西：

一个单纯作为知识库入口存在的可视化首页。打开 Obsidian 后，可以快速看到常用笔记、自己配置的项目、最近的知识库活动，并直接进入想找的内容；同时不需要为了仪表盘重新组织笔记，也不需要持续维护一篇特殊的首页笔记。

Lite Atlas 就是从这个需求里长出来的。

因此，Lite Atlas 面向的是个人知识库导航，尤其适合那些使用 Obsidian 时“阅读和查找多于日记写作”的用户。

它不是日记、任务管理器、习惯追踪器或写作分析工具，也不打算成为一套新的知识管理方法。

Lite Atlas 更希望覆盖在你已经存在的知识库之上，而不是要求你的知识库围绕 Lite Atlas 重新组织。

功能特性

• 自定义 Banner — 设置标题、副标题，以及知识库内任意位置的图片。
• 可视化日历 — 展示当前月份并高亮今天。
• 知识库活动热力图 — 展示最近 52 周按日持久保存的 Markdown 笔记活动。
• 知识库概览 — 展示知识库名称、Markdown 笔记数量、已配置项目数量及最近修改日期。
• 常用笔记 — 自动展示打开次数最多的五篇笔记，或使用手动选择的固定列表。
• 快速访问 — 新建笔记、打开模板文件夹、打开文件或定位文件夹。
• 轻量搜索 — 搜索 Markdown 文件名和正文内容。
• 项目看板 — 展示手动配置的项目、笔记数量、状态和精选笔记。
• 本地化界面 — 支持 English、简体中文及跟随 Obsidian 界面语言。
• 响应式布局 — 按 Lite Atlas Pane 的实际宽度适配桌面分栏、窄窗口与触摸导向的移动端布局。

安装方式

手动安装

1. 下载或构建以下文件：

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

2. 在知识库中创建以下目录：

   <知识库>/.obsidian/plugins/lite-atlas/
   

3. 将三个文件复制到该目录。

4. 重启 Obsidian 或重新加载应用。

5. 打开 设置 → 第三方插件，按需关闭安全模式，然后启用 Lite Atlas。

版本迁移

从手动安装的 0.2.0 直接升级至 0.2.2，并保留设置与活动数据时：

1. 禁用 Lite Atlas。
2. 将插件目录从 atlas 重命名为 lite-atlas。
3. 在重命名后的目录中保留既有 data.json 与 stats.json。
4. 使用 0.2.2 的 manifest.json、main.js 与 styles.css 替换运行时文件。
5. 重新启用 Lite Atlas。

从 0.1.0 直接升级至 0.2.2 时执行相同步骤，但将目录从 obsidian-atlas 重命名为 lite-atlas。历史上的 0.1.0 → 0.2.0 升级路径是将 obsidian-atlas 重命名为 atlas，0.2.0 → 0.2.1 则将 atlas 重命名为 lite-atlas。

从 0.2.1 升级至 0.2.2 不需要迁移目录或数据。保留 lite-atlas 目录，仅使用 0.2.2 的 manifest.json、main.js 与 styles.css 替换运行时文件。

Obsidian 社区插件市场

Lite Atlas 尚未获官方社区插件目录收录；提交与审核仍待进行。

使用方式

可以通过以下任一方式打开 Lite Atlas：

• 点击左侧 Ribbon 中的地图图标；
• 在命令面板中执行 打开仪表盘。

在 设置 → 第三方插件 → Lite Atlas 中配置仪表盘。

当前设置包括：

• 界面语言；
• Banner 图片、标题和副标题；
• 是否在 Obsidian 启动后自动打开；
• 自动或手动常用笔记；
• 模板文件夹；
• 项目分类；
• 项目文件夹、图标、状态、显示顺序和精选笔记。

Banner 图片建议

Banner 图片路径以知识库根目录为基准，例如：

banner.png
assets/banner.png
images/atlas/banner.png

Lite Atlas 先把路径解析为 Vault 内文件，再通过 Obsidian Vault API 读取，并使用进程内 Blob URL 渲染。缺失文件、绝对路径、UNC 路径和 file:// 值都会安全降级为无背景；filesystem path 不会进入 CSS。

为了获得比较稳定、可预测的裁切效果，推荐使用 4:1 比例的图片，例如 2400×600px。

Lite Atlas 使用居中的 cover 方式显示 Banner。由于实际可见区域会随着 Pane 宽度变化，因此更适合使用不依赖绝对主体位置的构图，而不是要求某个人物、物体或其他关键元素始终固定在画面的某个精确位置。

实际准备 Banner 时可以参考：

• 推荐比例为 4:1；
• 2400×600px 是一个合适的工作尺寸；
• 尽量避免必须保持精确位置的绝对主体；
• 重要视觉信息尽量集中在画布中央约 40% 的区域；
• 两侧区域尽量作为允许被裁切的安全空间；
• 不建议直接在图片中嵌入重要文字；
• 最终以自己常用的 Lite Atlas Pane 宽度实际查看裁切效果。

氛围图、风景、纹理、抽象构图以及主体位置相对自由的画面，通常都比较适合作为 Lite Atlas Banner。

活动数据与隐私

Lite Atlas 坚持非侵入式、local-only 设计：

• 不修改任何 Markdown 文件。
• 不引入自定义 Markdown 语法。
• 不保存笔记正文、frontmatter、编辑次数、写作时长或完整编辑日志。
• 只保存 Heatmap 所需的最小账本：客户端本地日历日期、Vault-relative Markdown 路径，以及启动 reconcile 所需的当前 mtime/size 观察状态。
• 同一篇 Markdown 笔记在同一客户端本地日期内无论修改多少次只计一次；以后日期的活动会新增，不会删除过去日期。
• Activity timestamp 按当前客户端本地时区映射为 YYYY-MM-DD。不同客户端可能把同一绝对时间映射到不同日期；Lite Atlas 不跨设备统一或重新分桶历史日期。
• Lite Atlas 监听 Obsidian Vault 的 create/modify/rename/delete 事件，并在启动时 reconcile 最后可观察文件状态；不假设第三方同步工具如何保留 mtime。
• 首次升级时，每篇当前 Markdown 最多按现有 mtime 导入一条 baseline activity。该 baseline 只表示升级时可观察的起点，不能恢复此前历史。
• 唯一持久化的交互统计是 Markdown 笔记打开次数，并且仅用于自动常用笔记。

插件设置与最小 Heatmap activity ledger 以版本化 envelope 保存在插件实际安装目录中。使用 Obsidian 默认配置目录和标准安装时，该路径为：

.obsidian/plugins/lite-atlas/data.json

常用笔记打开次数单独保存在 data.json 旁。使用相同默认值时，该路径为：

.obsidian/plugins/lite-atlas/stats.json

运行要求

• Obsidian 1.5.0 或更高版本
• Obsidian 桌面端

当前 manifest.json 将 Lite Atlas 标记为仅支持桌面端。

本地开发

环境要求：

• Node.js
• npm

安装依赖并执行生产构建：

npm install
npm run build

启动开发监听：

npm run dev

生产构建会将插件代码打包至 main.js。

项目结构

src/
├── components/    可复用的文件与文件夹选择器
├── i18n/          英文和简体中文翻译资源
├── search/        文件名和 Markdown 正文搜索
├── services/      设置、统计、主题与知识库数据服务
├── settings/      Obsidian 设置页
├── view/          仪表盘视图与布局
└── widgets/       Dashboard widgets

参与贡献与自行修改

Lite Atlas 最初就是一个为个人需求制作的小工具，因此现在的设计不可避免地带有某一种特定的 Obsidian 使用习惯。它不会适合所有知识库，也没有必要适合所有工作流。

欢迎提交 Issue 和 Pull Request。Bug 报告与聚焦的功能建议请使用 GitHub Issues。

如果你喜欢 Lite Atlas 的整体思路，但希望使用不同的布局、不同的 Widget、不同的统计方式，或者希望它更贴合自己的知识库，也非常欢迎直接 fork Lite Atlas，根据自己的需求修改。

并不是每一种个人定制需求都必须成为上游插件的正式功能。对于一个运行在本地的 Obsidian 插件来说，能够把它改成最适合自己知识库的样子，本身就是一种很自然的使用方式。

如果希望修改内容合并回 Lite Atlas 上游，请尽量遵循项目目前的核心原则：

• 不修改用户笔记；
• 后台活动追踪必须最小化、仅限 metadata，并保持 local-only；
• Widget 不直接负责设置存储、语言解析或主题实现；
• 新增用户可见文案时，同时提供英文与简体中文翻译。

作者

Nikoleta

许可证

Lite Atlas 使用 MIT License 开源。