feat: apply permalink to cli and assets manager

Author: virtualguard101

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/usage/cli.md

@@ -1,5 +1,5 @@
 ---
-date: 2025-11-05 20:30:00
+date: 2026-01-10 22:09: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`

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-note"
-version = "3.0.2"
+version = "3.1.0"
 description = "A MkDocs plugin to add note boxes to your documentation."
 readme = "README.md"
 requires-python = ">=3.12"

src/mkdocs_note/cli.py

@@ -127,23 +127,21 @@ def cli(ctx):
 
 
 @cli.command("new")
+@click.argument("permalink", required=True)
 @click.argument("file_path", required=True)
-@click.option(
-	"--template",
-	"-t",
-	type=click.Path(exists=True, path_type=Path),
-	help="Custom template file to use",
-)
 @click.pass_context
-def new_command(ctx, file_path, template):
+def new_command(ctx, permalink, file_path):
 	"""Create a new note file with proper asset structure.
 
 	\b
 	Examples:
-	    mkdocs-note new docs/notes/my-note.md
-	    mkdocs-note new docs/notes/python/intro.md
+	    mkdocs-note new my-permalink docs/notes/my-note.md
+	    mkdocs-note new python-intro docs/notes/python/intro.md
 
-	FILE_PATH: Path where the new note file should be created
+	\b
+	Arguments:
+	    PERMALINK: The permalink value for frontmatter and asset directory name
+	    FILE_PATH: Path where the new note file should be created
 	"""
 	try:
 		# Load configuration and setup environment
@@ -153,22 +151,30 @@ def new_command(ctx, file_path, template):
 		# Convert to Path
 		note_path = Path(file_path)
 
+		# Validate permalink
+		if not permalink or not permalink.strip():
+			click.echo("❌ Error: Permalink cannot be empty", err=True)
+			sys.exit(1)
+
+		permalink = permalink.strip()
+
 		# Check if file already exists
 		if note_path.exists():
 			click.echo(f"❌ Error: File already exists: {note_path}", err=True)
 			sys.exit(1)
 
 		# Create the note using NewCommand
 		command = NewCommand()
-		command.execute(note_path)
+		command.execute(permalink, note_path)
 
-		# Get asset directory path
-		asset_dir = cli_common.get_asset_directory(note_path)
+		# Get asset directory path based on permalink
+		asset_dir = cli_common.get_asset_directory_by_permalink(note_path, permalink)
 
 		# Check if creation was successful
 		if note_path.exists():
 			click.echo("✅ Successfully created note")
 			click.echo(f"📝 Note: {note_path}")
+			click.echo(f"🔗 Permalink: {permalink}")
 			click.echo(f"📁 Assets: {asset_dir}")
 			sys.exit(0)
 		else:
@@ -220,8 +226,15 @@ def remove_command(ctx, file_path, keep_assets, yes):
 			click.echo(f"❌ Error: File does not exist: {note_path}", err=True)
 			sys.exit(1)
 
-		# Get asset directory before removal
-		asset_dir = cli_common.get_asset_directory(note_path)
+		# Get asset directory before removal (based on permalink if available)
+		permalink = cli_common.get_permalink_from_file(note_path)
+		if permalink:
+			asset_dir = cli_common.get_asset_directory_by_permalink(
+				note_path, permalink
+			)
+		else:
+			# Fallback to filename-based for backwards compatibility
+			asset_dir = cli_common.get_asset_directory(note_path)
 		asset_exists = asset_dir.exists()
 
 		# Confirmation prompt (unless --yes)
@@ -238,9 +251,11 @@ def remove_command(ctx, file_path, keep_assets, yes):
 		# Check if removal was successful
 		if not note_path.exists():
 			click.echo(f"✅ Successfully removed note: {note_path}")
+			if permalink:
+				click.echo(f"🔗 Permalink: {permalink}")
 			if not keep_assets and asset_exists:
 				click.echo(f"📁 Removed assets: {asset_dir}")
-			else:
+			elif keep_assets:
 				click.echo(f"📁 Kept assets: {asset_dir}")
 			sys.exit(0)
 		else:
@@ -420,7 +435,7 @@ def clean_command(ctx, dry_run, yes):
 				sys.exit(0)
 
 		# Actually clean
-		click.echo("\n🗑️  Removing orphaned assets...")
+		click.echo("\n🗑️ Removing orphaned assets...")
 		command.execute(dry_run=False)
 
 		click.echo(