1st Timeline

1st Timeline

一个简单、优雅、中文友好的 Obsidian 时间轴渲染插件。 A simple, elegant, Chinese-friendly timeline rendering plugin for Obsidian. 当前版本 (Current version): 1.6.0

---

简介

1st Timeline 是一个 Obsidian 插件，可将简单的文本代码块渲染为精美的时间轴视图。支持多种日期格式（含中文日期优先支持），智能日期解析，优雅的视觉呈现——帮助您轻松创建时间线、项目进度视图或日程规划记录。

1st Timeline renders beautiful timeline views from simple text code blocks. It supports multiple date formats with first-class Chinese date support, intelligent parsing, and elegant visual presentation.

---

安装

从 Obsidian 社区插件市场（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 关闭"安全模式"
3. 点击"浏览"，搜索 "1st Timeline"
4. 安装并启用

从 GitHub Releases 安装

1. 前往 Releases 页面
2. 下载最新版本的 main.js、manifest.json、styles.css
3. 在 vault 中创建目录 .obsidian/plugins/first-timeline/
4. 将三个文件放入该目录
5. 重启 Obsidian，在 设置 → 社区插件 中启用

从源码构建

git clone https://github.com/lnabc03/1st-Timeline.git
cd 1st-Timeline
npm install
npm run build

然后将 main.js、manifest.json、styles.css 复制到 .obsidian/plugins/first-timeline/，重启并启用。

注意: 目标目录名必须与 manifest.json 中的 id 字段一致（first-timeline）。

---

使用方法

在 Obsidian 笔记中插入 timeline 代码块：

```timeline
2024-01-01  新年第一天（双空格分隔）
2024年3月8日：妇女节（中文冒号分隔）
2024-05-01: 劳动节（英文冒号分隔）
2025-01-28_12:04  精确时间格式
2025年1月29日早上  中文日期+时间词
2026-01-01
新的一年开始了！（多行文本）
- 支持完整的 Markdown 语法
# 标题
> 引用块
> [!NOTE] Callout
| A | B |
|---|---|
| C | D |
```

语法规则

时间段（日期范围）

除了时间点事件，还可以用 日期A～日期B：内容 表示一段有明确起止的时间（如实习、项目周期），渲染为时间轴上方的横向进度条：

```timeline
2026-07-01～2026-09-30：暑期实习
2026年8月1日至2026年8月20日：项目冲刺
2026-09-01~2026-09-10  双空格分隔也可以
```

• 起止日期支持 YYYY-MM-DD 和 YYYY年MM月DD日 两种纯日期格式
• 分隔符支持 ～、~、至、到 四种写法
• 状态自动计算：进行中显示「第 x/n 天」（开始当天为第 0 天），未开始显示「还有 x 天开始」，已结束显示「已结束 x 天」
• 进度条颜色跟随时间轴颜色：未开始不填充，进行中按比例填充，已结束填满并降低透明度
• 起止同一天时退化为普通时间点事件；开始晚于结束时自动交换
• 时间段的开始日和结束日会在时间轴上渲染为主题色水平分隔线（「标题（开始）」「标题（结束）」），与进度条一一对应；开始线自动排在当日所有事件上方、结束线排在下方，可在设置中关闭
• 自动折叠时只显示进行中的进度条

时间轴链接

用 source: 指令引用另一个笔记中的时间轴，避免在日记模板里重复硬编码相同的事件：

```timeline
source: [[工作安排]]
2026-08-20：只属于本篇笔记的事件
```

• 被引用的笔记中，事件需写在 ```timeline 代码块内（可混写其他任意内容）
• 指令关键字支持 source: 和 源：（中英文冒号均可），可出现在代码块任意位置，仅第一个生效
• 引用的事件与代码块内的事件合并排序渲染；日期和内容完全相同的条目自动去重（代码块内优先）
• 链接解析与 Obsidian 内链规则一致，文件改名后可自动跟踪；源文件修改后重新打开笔记即可刷新

归档过期事件

在包含时间轴的笔记中执行命令面板的 "归档过期事件 / Archive past events" 命令：

• 当前文件所有 ```timeline 代码块中，日期早于今天的事件会被移出代码块
• 时间段以结束日期判断：已结束的时间段会被归档，进行中/未开始的保留
• 过期事件追加到同文件的「已归档：」区域（纯文本保留原始格式）；区域不存在时在文件末尾自动创建
• 重复执行时识别已有归档区并追加，今天及未来的事件保留在块内

笔记汇总

使用命令面板（Ctrl+P）执行 "笔记汇总 / Notes summary" 命令：

1. 输入日期范围（格式：YYYY-MM-DD,YYYY-MM-DD）
2. 默认填充当前月份
3. 确认后自动生成基于指定 frontmatter 属性的笔记时间轴

---

设置选项

---

开发

对齐 Obsidian 官方示例插件 最佳实践：

npm install          # 安装依赖
npm run dev          # 开发模式（watch）
npm run build        # 生产构建（tsc + esbuild）
npm run lint         # ESLint 代码检查

• 语言: TypeScript（strict 模式）
• 构建: esbuild（CJS 输出，ES2021 target）
• 代码检查: ESLint 9 + typescript-eslint + eslint-plugin-obsidianmd
• CI/CD: GitHub Actions（lint + release）
• 最低 Obsidian 版本: 1.8.7（桌面及移动端）

---

更新日志

1.6.0 — 端点分隔线 (2026-08)

• 时间段起止日期渲染为时间轴上的主题色水平分隔线：文字居中，线条向两端延伸渐隐，悬浮时提亮
• 同日包含排序：开始分隔线自动排在当日所有事件上方，结束分隔线排在下方
• 新增「时间段端点标记」设置开关；移除进度条显示开关（进度条改为常显）

1.5.x — 时间段与生态完善 (2026-07)

• 新增时间段（日期范围）语法 日期A～日期B：内容，渲染为时间轴上方的进度条，自动计算第 x/n 天
• 新增 source: 指令引用其他笔记的时间轴、归档过期事件命令
• 通过社区插件审核，适配 Obsidian 1.13.0+ 设置搜索

1.4.x — 正式版发布 (2026-06)

• TypeScript 重构、多模块架构、esbuild 构建，完全对齐 Obsidian 官方模板
• 中英文双语支持，自动检测 Obsidian 语言设置
• 重新设计当天事件高亮（内嵌强调色条 + 徽章）
• 移动端全面适配：响应式布局、日期完整显示、光点精准居中
• 社区插件市场上架并通过审核

1.3.x — 自动折叠与笔记汇总 (2025)

• 新增自动折叠和笔记汇总功能
• 修复日期解析相关问题

1.2.x — 交互增强 (2025)

• 添加悬停提示（距今天数）和当天事件高亮

1.1.x — 中文支持 (2025)

• 增加中文日期格式支持和颜色预设主题

1.0.0 — 初始版本 (2025)

• 基础时间轴渲染

---

许可证

MIT License

---

作者

lnabc03 | 弋鹓

---

---

1st Timeline

A simple, elegant, Chinese-friendly timeline rendering plugin for Obsidian. 一个简单、优雅、中文友好的 Obsidian 时间轴渲染插件。 Current version: 1.6.0

Description

1st Timeline renders beautiful timeline views from simple text code blocks. It supports multiple date formats with first-class Chinese date support, intelligent parsing, and elegant visual presentation — helping you create timelines, project progress views, or schedule records effortlessly.

1st Timeline 是一个 Obsidian 插件，可将简单的文本代码块渲染为精美的时间轴视图。

Installation

From Obsidian Community Plugin Marketplace (Recommended)

1. Open Obsidian Settings → Community plugins
2. Disable Safe mode
3. Click Browse, search for "1st Timeline"
4. Install and enable

From GitHub Releases

1. Go to the Releases page
2. Download the latest main.js, manifest.json, and styles.css
3. Create the directory .obsidian/plugins/first-timeline/ in your vault
4. Copy the three files into that directory
5. Restart Obsidian and enable the plugin in Settings → Community plugins

From Source

git clone https://github.com/lnabc03/1st-Timeline.git
cd 1st-Timeline
npm install
npm run build

Then copy main.js, manifest.json, and styles.css to .obsidian/plugins/first-timeline/, restart Obsidian, and enable.

Note: The target directory name must match the id field in manifest.json (first-timeline).

Usage

Insert a timeline code block in any Obsidian note:

```timeline
2024-01-01  New Year's Day (two spaces)
2024-03-08: International Women's Day (colon)
2024年5月1日：Labor Day (Chinese date + colon)
2025-01-28_12:04  Precise time format
2025年1月29日早上  Chinese date with time-of-day word
2026-01-01
A new year begins! (multi-line text)
- Full Markdown syntax supported
# Headings
> Blockquotes
> [!NOTE] Callouts
| A | B |
|---|---|
| C | D |
```

Syntax Rules

Date Ranges

Beyond point-in-time events, use DateA～DateB: content for a span with explicit start and end (e.g. an internship or project phase), rendered as horizontal progress bars above the timeline:

```timeline
2026-07-01～2026-09-30: Summer internship
2026年8月1日至2026年8月20日：Project sprint
2026-09-01~2026-09-10  Two-space separator works too
```

• Start and end accept pure dates only: YYYY-MM-DD or YYYY年MM月DD日
• Four separators are recognized: ～, ~, 至, 到
• Status is computed automatically: "Day x/n" while active (day 0 on the start date), "Starts in x days" when upcoming, "Ended x days ago" when over
• Bar color follows the timeline color: empty when upcoming, proportional fill while active, full but dimmed when ended
• Identical start and end degrades to a normal point event; a start later than the end is swapped automatically
• Each range's start and end dates render as theme-colored horizontal divider lines on the timeline ("Title (Start)" / "Title (End)"), matching the progress bars one-to-one; the start divider ranks above all same-day events and the end divider below — can be turned off in settings
• When collapsed, only active bars are shown

Timeline Source

Use the source: directive to render a timeline stored in another note, avoiding hardcoded duplicates in daily note templates:

```timeline
source: [[Work Schedule]]
2026-08-20: An event unique to this note
```

• In the referenced note, events must live inside a ```timeline code block (other content is allowed)
• The directive accepts source: or 源： (either colon), may appear anywhere in the block, and only the first one takes effect
• Referenced events are merged and sorted with inline events; entries with identical date and content are deduplicated (inline wins)
• Link resolution follows Obsidian's internal link rules and survives file renames; reopen the note to refresh after editing the source file

Archive Past Events

Run the "Archive past events / 归档过期事件" command from the command palette in a note containing timelines:

• Events dated before today are moved out of every ```timeline code block in the current file
• Date ranges are judged by their end date: ended ranges are archived, active/upcoming ones stay
• Archived events are appended to an "Archived:" section in the same file (kept as plain text in original format); the section is created at the end of the file if absent
• Running the command again appends to the existing section; today's and future events stay in the block

Notes Summary

Use the command palette (Ctrl+P) and run the "Notes summary / 笔记汇总" command:

1. Enter a date range (format: YYYY-MM-DD,YYYY-MM-DD)
2. The current month is pre-filled by default
3. Confirm to insert a timeline of notes based on the configured frontmatter date field

Settings

Development

Follows Obsidian's official sample plugin best practices:

npm install          # Install dependencies
npm run dev          # Development mode (watch)
npm run build        # Production build (tsc + esbuild)
npm run lint         # ESLint check

• Language: TypeScript (strict mode)
• Build: esbuild (CJS output, ES2021 target)
• Linting: ESLint 9 + typescript-eslint + eslint-plugin-obsidianmd
• CI/CD: GitHub Actions (lint + release)
• Minimum Obsidian version: 1.8.7 (desktop and mobile)

Changelog

1.6.0 — Endpoint Dividers (2026-08)

• Range start/end dates render as theme-colored horizontal divider lines on the timeline: centered text, lines fading out to both sides, brightening on hover
• Same-day inclusion ordering: the start divider ranks above all events on its day, the end divider below
• New "Range start/end markers" setting toggle; removed the progress-bar visibility setting (bars are now always shown)

1.5.x — Date Ranges & Ecosystem (2026-07)

• Added date range syntax DateA～DateB: content, rendered as progress bars above the timeline with automatic day x/n tracking
• Added the source: directive for referencing timelines in other notes, and the archive past events command
• Passed community plugin review; compatible with Obsidian 1.13.0+ settings search

1.4.x — Official Release (2026-06)

• TypeScript rewrite, multi-module architecture, esbuild build system, aligned with Obsidian template
• Bilingual Chinese/English support with automatic language detection
• Redesigned today-event highlighting (inset accent strip + badge)
• Full mobile adaptation: responsive layout, full date display, precise dot centering
• Published to Obsidian community plugin marketplace

1.3.x — Auto Collapse & Notes Summary (2025)

• Added auto-collapse and notes summary features
• Fixed date parsing issues

1.2.x — Interaction Enhancements (2025)

• Added hover tooltips (days until/since) and today highlighting

1.1.x — Chinese Support (2025)

• Added Chinese date format support and color preset themes

1.0.0 — Initial Release (2025)

• Basic timeline rendering

License

MIT License

Author

lnabc03 | 弋鹓