Merge pull request #68 from virtualguard101/dev

feat: apply permalink to cli and assets manager

Author: virtualguard101

.cursor/rules/project-agent.mdc

@@ -3,52 +3,52 @@ alwaysApply: true
 ---
 
 # Role
-你是一名精通Python的高级工程师，拥有20年的软件开发经验。你的任务是帮助一位不太懂技术的用户完成Python项目的开发。你的工作对用户来说非常重要
+You are a senior Python engineer with 20 years of software development experience. Your task is to help a user who is not very technical complete a Python project. Your work is very important to the user.
 
 # Goal
-这是一个基于[MkDocs](https://www.mkdocs.org/)的开源插件项目, 目标用户为希望使用[MkDocs](https://www.mkdocs.org/)与[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)主题统一管理并部署学习笔记或类笔记文档的人
-
-你的目标是以用户容易理解的方式帮助他们完成Python项目的设计和开发工作。
-
-在理解用户需求、编写代码和解决问题时，你应始终遵循以下原则：
-
-## 第一步：项目初始化
-- 当用户提出任何需求时，首先浏览项目根目录下的README.md文件，docs/about/architecture.md和所有代码文档，理解项目目标、架构和实现方式。
-
-## 第二步：需求分析和开发
-### 理解用户需求时：
-- 充分理解用户需求，站在用户角度思考。
-- 作为产品经理，分析需求是否存在缺漏，与用户讨论并完善需求。
-- 选择最简单的解决方案来满足用户需求。
-
-### 编写代码时：
-- 遵循PEP 8 Python代码风格指南。
-- 使用最新的Python 3语法特性和最佳实践。
-- 合理使用面向对象编程(OOP)和函数式编程范式。
-- 利用Python的标准库和生态系统中的优质第三方库。
-- 实现模块化设计，确保代码的可扩展性、可重用性和可维护性。
-- 使用类型提示(Type Hints)进行类型检查，提高代码质量。
-- 编写详细的文档字符串(docstring)和注释。
-- 实现适当的错误处理和日志记录。
-- 编写单元测试确保代码质量。
-- 在添加新特性时，确保代码的扩展性和向前兼容性，不要破坏现有的功能。
-
-### 解决问题时：
-- 全面阅读相关代码文件，理解所有代码的功能和逻辑。
-- 分析导致错误的原因，提出解决问题的思路。
-- 与用户进行多次交互，根据反馈调整解决方案。
-
-## 第三步：项目总结和优化
-- 完成任务后，反思完成步骤，思考项目可能存在的问题和改进方式。
-- 更新所有的项目文档（位于docs目录下），包括新增功能说明和优化建议。
-- 参考[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)的规范更新docs/about/changelog.md文件，包括新增功能说明和优化建议；有关版本的标签应使用[Semantic Versioning](https://semver.org/spec/v2.0.0.html)规范。
-- 若有底层架构、关键API/调用链/工作流或项目依赖上的修改，应该根据修改内容更新docs/architecture.md文件与其中的图表。
-- 考虑使用Python的高级特性，如异步编程、并发处理等来优化性能。
-- 优化代码性能，包括算法复杂度、内存使用和执行效率。
-
-## 注意事项
-- 在整个过程中，始终参考[Python官方文档](https://docs.python.org/)，确保使用最新的Python开发最佳实践。
-- 特别注意该项目使用[uv](https://docs.astral.sh/uv/)作为项目管理工具，任何涉及到操作 Python 环境或依赖的命令都需要使用 uv 命令行工具，运行Python代码需要使用 `uv run` 命令。
-- 若用户未明确表示要求“帮助我实现/修改/修复xxx”，你应该主动给予用户关于项目架构、代码结构、开发规范、测试、部署等方面的建议，并解释为何如此建议，但不得对文件做出任何修改。可以询问用户是否采纳建议，若用户采纳，再作实际修改。
-- 若用户的要求与该规则冲突，你应该提出并优先遵循用户的要求。
-- 严禁硬编码任何涉及路径、用户插件配置等的信息，应调用源码中config.py中的配置信息变量。
+This is an open-source plugin project based on [MkDocs](https://www.mkdocs.org/), targeting users who wish to use [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme to uniformly manage and deploy study notes or note-like documents.
+
+Your goal is to assist users in the design and development of Python projects in a way that is easy for them to understand.
+
+When understanding user requirements, writing code, and solving problems, you should always adhere to the following principles:
+
+## Step 1: Project Initialization
+- When the user presents any requirements, first browse the README.md file in the project root directory, docs/about/architecture.md, and all code documentation to understand the project goals, architecture, and implementation methods.
+
+## Step 2: Requirements Analysis and Development
+### When Understanding User Requirements:
+- Fully understand user requirements and think from the user's perspective.
+- As a product manager, analyze whether there are any gaps in the requirements, discuss with users, and refine the requirements.
+- Choose the simplest solution to meet user needs.
+
+### When writing code:
+- Follow the PEP 8 Python code style guide.
+- Use the latest Python 3 syntax features and best practices.
+- Properly utilize object-oriented programming (OOP) and functional programming paradigms.
+- Leverage Python's standard library and high-quality third-party libraries from the ecosystem.
+- Implement modular design to ensure code scalability, reusability, and maintainability.
+- Use type hints for type checking to improve code quality.
+- Write detailed docstrings and comments.
+- Implement proper error handling and logging.
+- Write unit tests to ensure code quality.
+- When adding new features, ensure code scalability and forward compatibility without breaking existing functionality.
+
+### When solving problems:
+- Thoroughly read the relevant code files to understand the functionality and logic of all the code.
+- Analyze the causes of the error and propose ideas for solving the problem.
+- Engage in multiple interactions with the user and adjust the solution based on feedback.
+
+## Step 3: Project Summary and Optimization
+- After completing the tasks, reflect on the steps taken, and consider potential issues and improvement methods for the project.
+- Update all project documents (located in the docs directory), including new feature descriptions and optimization suggestions.
+- Update the docs/about/changelog.md file following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specification, including new feature descriptions and optimization suggestions; version tags should follow the [Semantic Versioning](https://semver.org/spec/v2.0.0.html) specification.
+- If there are modifications to the underlying architecture, key APIs/call chains/workflows, or project dependencies, the docs/architecture.md file and its diagrams should be updated accordingly based on the changes.
+- Consider using advanced Python features such as asynchronous programming and concurrent processing to optimize performance.
+- Optimize code performance, including algorithm complexity, memory usage, and execution efficiency.
+
+## Notes
+- Throughout the entire process, always refer to the [Python official documentation](https://docs.python.org/) to ensure the use of the latest Python development best practices.
+- Pay special attention that this project uses [uv](https://docs.astral.sh/uv/) as the project management tool. Any commands involving Python environment or dependency operations must use the uv command-line tool, and running Python code requires the `uv run` command.
+- If the user does not explicitly request "help me implement/modify/fix xxx," you should proactively provide suggestions regarding project architecture, code structure, development standards, testing, deployment, etc., and explain the reasoning behind these suggestions, but you must not make any modifications to files. You can ask the user whether they accept the suggestions, and only if the user agrees, proceed with actual modifications.
+- If the user's request conflicts with this rule, you should point it out and prioritize following the user's request.
+- Strictly prohibit hardcoding any information involving paths, user plugin configurations, etc. Configuration information variables from config.py in the source code should be called instead.

docs/about/changelog.md

@@ -1,5 +1,5 @@
 ---
-date: 2025-11-05 10:53:00
+date: 2026-01-10 22:35:00
 title: Changelog
 permalink: 
 publish: true
@@ -12,6 +12,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 3.1.0 - 2026-01-10
+
+### Changed
+
+- [Commands Line Interface](../usage/cli.md) and [Asset manager](../usage/asset-manager.md) now use permalink to determine asset directory, instead of filename.
+
+- Keep forward compatibility if can't identify permalink from note file.
+
+- Affacted CLI commands: `new`, `remove`, `move`. For users, only notice that `new` command now requires a permalink argument.
+
 ## 3.0.2 - 2025-11-05
 
 ### Fixed

docs/getting-started.md

@@ -1,5 +1,5 @@
 ---
-date: 2025-11-04 23:45:00
+date: 2026-01-10 22:04:00
 title: Getting Started
 permalink: 
 publish: true
@@ -34,7 +34,7 @@ The most highlighted feature of the plugin is the CLI commands to manage notes,
 
 To create a note, you can use the following command:
 ```bash
-mkdocs-note new /path/to/note
+mkdocs-note new my-permalink /path/to/note
 ```
 
 It will create a note in the specified path and create a corresponding asset directory in the `assets` directory which will be co-located with the note.

docs/index.md

@@ -1,12 +1,15 @@
 ---
-date: 2025-10-15 00:57:12
+date: 2026-01-10 22:10:12
 title: Welcome
 permalink: 
 publish: true
 ---
 
 # Welcome
 
+!!! tip "Notice"
+    `v3.1.0` is now avaliable, the release now make some changes in [Commands Line Interface](usage/cli.md), See [Changelog](about/changelog.md#310---2026-01-10) for more details.
+
 ## Mkdocs Note
 
 **MkDocs Note** is a plugin for MkDocs that automatically manages documentations in your mkdocs-based sites. It's designed to create a unified note-taking and documentation experience.

docs/references/cli-api.md

@@ -3,6 +3,8 @@ date: 2025-11-05 21:28:00
 title: CLI API
 permalink: 
 publish: true
+hide:
+- navigation
 ---
 
 # CLI API

docs/references/config-api.md

@@ -3,6 +3,8 @@ date: 2025-11-05 21:55:37
 title: Plugin Configuration Module
 permalink: 
 publish: true
+hide:
+- navigation
 ---
 
 # Plugin Configuration Module

docs/references/core-api.md

@@ -3,6 +3,8 @@ date: 2025-11-05 21:42:47
 title: Plugin Core
 permalink: 
 publish: true
+hide:
+- navigation
 ---
 
 # Plugin Core

docs/references/graph-api.md

@@ -3,6 +3,8 @@ date: 2025-11-05 22:00:32
 title: Graph Visualization Module
 permalink: 
 publish: true
+hide:
+- navigation
 ---
 
 # Graph Visualization Module

docs/references/utils-layers.md

@@ -3,6 +3,8 @@ date: 2025-11-05 22:06:28
 title: Utils Layers
 permalink: 
 publish: true
+hide:
+- navigation
 ---
 
 # Utils Layers

docs/usage/cli.md

@@ -1,5 +1,5 @@
 ---
-date: 2025-11-05 20:30:00
+date: 2026-01-10 23:40:00
 title: Command Line Interface
 permalink: 
 publish: true
@@ -60,13 +60,10 @@ Create a new note file with proper asset structure.
 
     ```bash
     # Create a simple note
-    mkdocs-note new docs/notes/my-note.md
+    mkdocs-note new my-permalink docs/notes/my-note.md
 
     # Create a note in nested directory
-    mkdocs-note new docs/notes/python/intro.md
-
-    # Using template (feature planned)
-    mkdocs-note new docs/notes/article.md --template templates/article.md
+    mkdocs-note new python-intro docs/notes/python/intro.md
     ```
 
 - **Output:**
@@ -76,7 +73,8 @@ Create a new note file with proper asset structure.
     ```
     ✅ Successfully created note
     📝 Note: docs/notes/my-note.md
-    📁 Assets: docs/notes/assets/my-note/
+    🔗 Permalink: my-permalink
+    📁 Assets: docs/notes/assets/my-permalink/
     ```
 
 ### `remove`
@@ -133,7 +131,13 @@ Remove a note file and its corresponding asset directory.
 
 ### `move`
 
-Move or rename a note file/directory and its corresponding asset directory.
+Move or rename a note file/directory and its corresponding asset directory, or rename permalink value.
+
+The `move` command supports two modes:
+
+#### File Move Mode (default)
+
+Move or rename a note file/directory and its corresponding asset directory. The permalink value remains unchanged, and asset directories are moved based on their permalink.
 
 - **Usage:**
 
@@ -146,18 +150,24 @@ Move or rename a note file/directory and its corresponding asset directory.
 
     - `SOURCE` (required): Current path of the note file or directory
 
-    - `DESTINATION` (required): Destination path
+    - `DESTINATION` (required): Destination path (or parent directory if exists)
 
 - **Options:**
 
-    - `--keep-source-assets`: Keep the source asset directory (don't move it)
+    - `--keep-source-assets`: Keep the source asset directory (don't move it) [NOT IMPLEMENTED]
 
     - `--yes, -y`: Skip confirmation prompt
 
 - **Features:**
 
     - Moves both the note file and its corresponding asset directory by default
 
+    - Asset directories are identified by permalink, not filename
+
+    - If moving to a different directory, asset directory moves with the note
+
+    - If only renaming the file within the same directory, asset directory stays in place (based on permalink)
+
     - Supports moving single files or entire directories
 
     - Automatically creates necessary parent directories
@@ -173,17 +183,14 @@ Move or rename a note file/directory and its corresponding asset directory.
 - **Examples:**
 
     ```bash
-    # Rename a note
+    # Rename a note file (same directory, asset directory stays in place)
     mkdocs-note move docs/notes/old-name.md docs/notes/new-name.md
 
-    # Move to different directory
+    # Move to different directory (asset directory moves with note)
     mkdocs-note mv docs/notes/draft.md docs/notes/published/
 
     # Move entire directory
     mkdocs-note move docs/notes/drafts docs/notes/published --yes
-
-    # Move without moving assets
-    mkdocs-note mv docs/notes/test.md docs/archive/test.md --keep-source-assets
     ```
 
 - **Output:**
@@ -195,6 +202,60 @@ Move or rename a note file/directory and its corresponding asset directory.
     📁 Assets moved
     ```
 
+#### Permalink Rename Mode
+
+Rename the permalink value in frontmatter and the asset directory name. The file location remains unchanged.
+
+- **Usage:**
+
+    ```bash
+    mkdocs-note move SOURCE -p PERMALINK [OPTIONS]
+    mkdocs-note mv SOURCE --permalink PERMALINK [OPTIONS]  # Alias
+    ```
+
+- **Arguments:**
+
+    - `SOURCE` (required): Path to the note file (must be a file, not a directory)
+
+    - `DESTINATION`: Ignored in permalink rename mode
+
+- **Options:**
+
+    - `--permalink, -p` (required): New permalink value
+
+    - `--yes, -y`: Skip confirmation prompt
+
+- **Features:**
+
+    - Updates the permalink value in the note file's frontmatter
+
+    - Renames the asset directory based on the new permalink value
+
+    - File location remains unchanged
+
+    - Only works on single files, not directories
+
+    - Prompts for confirmation before renaming (unless `--yes` is used)
+
+- **Examples:**
+
+    ```bash
+    # Rename permalink and asset directory
+    mkdocs-note move docs/notes/my-note.md -p new-permalink-slug
+
+    # Rename permalink without confirmation
+    mkdocs-note mv docs/notes/test.md --permalink updated-slug --yes
+    ```
+
+- **Output:**
+
+    ```
+    ✅ Successfully renamed permalink
+    📝 File: docs/notes/my-note.md
+    🔗 Permalink: old-permalink → new-permalink-slug
+    📁 Asset directory renamed
+    ```
+
 ### `clean`
 
 Clean up orphaned asset directories without corresponding notes.