refactor: refactor underlying architecture and greatly simplified the framework

docs/getting-started.md

@@ -1,5 +1,5 @@
 ---
-date: 2025-10-16 14:06:23
+date: 2025-11-04 23:45:00
 title: Getting Started
 permalink: 
 publish: true
@@ -26,135 +26,80 @@ pip install mkdocs-note
 
 For more details, please refer to the [Installation | User Guide](usage/installation.md).
 
-## Configuration
-
-### Basic Configuration
-
-For basic configuration, you can add the following to your `mkdocs.yml`:
-
-```yml
-plugins:
-  - mkdocs-note
-```
-
-It's the simplest configuration, and the plugin will use the default configuration.
+## Use CLI to manage notes
 
-### Recommended Configuration
+The most highlighted feature of the plugin is the CLI commands to manage notes, which can help you manage your notes with their corresponding assets **atomically**.
 
-For recommended configuration, you can add the following to your `mkdocs.yml`:
+### Create a note
 
-```yml
-plugins:
-  - mkdocs-note:
-      notes_dir: "docs/notes"
-      index_file: "docs/index.md"
-      start_marker: "<!-- recent_notes_start -->"
-      end_marker: "<!-- recent_notes_end -->"
-      max_notes: 10
-      supported_extensions: [".md"]
-```
-
-In general, Mkdocs Note supports highly customizable configuration, you can configure the plugin to your own needs.
-
-Please refer to the [Configuration Options | User Guide](usage/config.md) for more details about the information of each configuration options.
-
-## Create Your Note Boxes
-
-### Manual Setup
-
-1. Create the notes directory you have just configured above in your mkdocs project (e.g., `docs/notes`)
-
-2. Create an `index.md` file in your notes directory manually.
-
-3. Add the marker comments to your index file:
-
-```markdown
-# My Notes
-
-<!-- recent_notes_start -->
-<!-- recent_notes_end -->
+To create a note, you can use the following command:
+```bash
+mkdocs-note new /path/to/note
 ```
 
-For index files (`index.md`), the default configuration will not allow CLI tools to create it automatically, so you need to create it manually. See more details in [Exclusion](usage/exclusion.md) and [Something You Should Notice | Recent Notes Insertion](usage/recent-notes.md#Something-You-Should-Notice) about it.
-
-### Use CLI Commands
-
-The plugin provides several CLI commands for docs and their assets management.
-
-And first of all, this is a mkdocs-based plugin, so you need to have a mkdocs project first.
-
-#### Validate Structure
+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.
 
-Use following command to validate the structure of your docs and assets:
+### Remove Note or Note Directory
 
+To remove a note, you can use the following command:
 ```bash
-mkdocs-note validate [--path PATH]
+mkdocs-note remove /path/to/note-or-directory
 ```
 
-This command will check if the structure of your docs and assets is compliant with the plugin's design.
+It will remove the note or note directory and the corresponding asset directory(ies) from the `assets` directory, inspired by shell command `rm -rf`.
 
-If there are any issues, it will report them to you.
-
-#### Initialize Docs and Assets Structure
-
-Use following command to initialize your mkdocs-based docs and assets structure:
+### Move or Rename Note or Note Directory
 
+To move or rename a note or note directory, you can use the following command:
 ```bash
-mkdocs-note init [--path PATH]
+mkdocs-note move /path/to/note-or-directory /path/to/new-location
 ```
 
-If your docs already has a structure, this command will analyze the existing asset structures and fix the non-compliant asset trees.
-
-However, it will not help you move your existing assets to the new structure.
-
-For example, if you have a note in `docs/notes/my-note.md`, and the asset is in `docs/assets/notes/my-note/`, this command will not help you move the asset to `docs/assets/my-note/`.
+It will move or rename the note or note directory and the corresponding asset directory(ies) to the new location, inspired by shell command `mv`.
 
-And take a look at the entire plugin in `v2.0.0`,there has no way to move the asset to the new structure automatically, so you need to do it manually and we're now trying to add this optional feature in the future.
+More details, please refer to the [CLI Commands | User Guide](usage/cli.md).
 
-By the way, if you're really don't want to move your existing assets to the new structure, you can puts them out of the config option `notes_dir` and use legency way to link them in order to avoid the plugin automatically managing them and cause some undefined events.
+## Configuration
 
-#### Create New Documentation
+### Basic Configuration
 
-Use following command to create a new documentation:
+For basic configuration, you can add the following to your `mkdocs.yml`:
 
-```bash
-mkdocs-note new FILE_PATH
+```yml
+plugins:
+  - mkdocs-note
 ```
 
-This command will create a new note file with the default template and the corresponding asset directory, which is a bit like [`hexo new`](https://hexo.io/zh-cn/docs/commands#new) command in Hexo.
+It's the simplest configuration, and the plugin will use the default configuration.
 
-#### Remove Existing Documentation
+### Recommended Configuration
 
-Use following command to remove an existing documentation:
+To use the plugin in a recommended way, you can add the following to your `mkdocs.yml`:
 
-```bash
-mkdocs-note remove FILE_PATH
+```yml
+plugins:
+  - mkdocs-note:
+      recent_notes_config:
+        enabled: true
+        insert_marker: "<!-- recent_notes -->"
+        insert_num: 5
+      graph_config:
+        enabled: true
+        name: "title"
+        debug: false
 ```
 
-This command will remove the documentation file and its corresponding asset directory, and before doing that, it will ask you for confirmation.
-
-And you can use the alias `mkdocs-note rm` to do the same thing.
-
-#### Other Commands
+## Recent Notes Insertion
 
-There are some other commands that are not mentioned here, you can use `mkdocs-note --help/-h` or `mkdocs-note <command> --help/-h` to get the full list of commands and their usage.
+Mkdocs Note supports inserting specified number of recent notes to the marked placeholder in the index file, which can be configured in `mkdocs.yml` as follows:
 
-#### Configuration Auto-Loading
-
-All CLI commands automatically load your custom configuration from `mkdocs.yml` in the current or parent directories. You can also specify a config file explicitly using `--config` or `-c` option:
-
-```bash
-mkdocs-note --config path/to/mkdocs.yml <command>
+```yml
+plugins:
+  - mkdocs-note:
+      recent_notes_config:
+        enabled: true
+        insert_marker: "<!-- recent_notes -->"
+        insert_num: 5
 ```
 
-## Getting Help
-
-See the [User Guide](usage/index.md) for more details about the usage and features of the plugin.
-
-This project is still in its infancy stage, so any feedback or suggestions are welcome.
-
-You can open an issue on [GitHub](https://github.com/virtualguard101/mkdocs-note/issues) to report bugs or request features.
-
-Or you can email me directly at [virtualguard101@gmail.com](mailto:virtualguard101@gmail.com), though I may respone late because of my busy schedule.
-
-Thank you for using MkDocs Note!
+More details, please refer to the [Recent Notes Insertion | User Guide](usage/recent-notes.md).

docs/index.md

@@ -11,7 +11,11 @@ publish: true
 
 **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.
 
-## Recent New or Modified Documentations
+!!! warning "Notice"
+    Due to the manual refactoring of the codebase, the release `v3.0.0` has some large breaking changes which some docs hasn't been updated yet.
+
+    In the [Recent Update](#Recent-Update) below, documentations whose timestamp after November, 2025 is updated those.
 
-<!-- recent_notes_start -->
-<!-- recent_notes_end -->
+## Recent Update
+
+<!-- recent_notes -->

docs/usage/cli.md

@@ -2,143 +2,14 @@
 date: 2025-10-17 10:58:59
 title: Command Line Interface
 permalink: 
-publish: true
+publish: false
 ---
 
 # Command Line Interface
 
-`mkdocs-note` provides a command line interface for documentation management. You can use the command line interface to manage your documentations and their assets correspondingly.
+`mkdocs-note` provides a command line interface for documentation management.
 
-## Overview
-
-| Command | Description |
-|---------|-------------|
-| `mkdocs-note init` | Initialize the notes directory structure |
-| `mkdocs-note new` | Create a new note file with template content |
-| `mkdocs-note validate` | Validate the asset tree structure |
-| `mkdocs-note template` | Manage the template file |
-| `mkdocs-note remove`/`rm` | Remove a note file and its corresponding asset directory |
-| `mkdocs-note clean` | Clean orphaned assets |
-| `mkdocs-note move`/`mv` | Move or rename a note file or directory |
-
-For overview in command line, you can use the `--help/-h` option to get the help information of all commands.
-```bash
-mkdocs-note --help
-# Or
-mkdocs-note -h
-```
-
-For detailed information of a specific command, you can use the `mkdocs-note <command> --help` command to get the help information of a command.
-```bash
-mkdocs-note <command> --help
-```
-
-## Configuration Auto-Loading
-
-All CLI commands automatically load your custom configuration from `mkdocs.yml` in the current or parent directories. You can also specify a config file explicitly using `--config` or `-c` option:
-
-```bash
-mkdocs-note --config path/to/mkdocs.yml <command>
-```
-
-## Commands Details
-
-### Initialize Notes Directory
-
-```bash
-mkdocs-note init [--path PATH]
-```
-
-- Creates the docs and assets directory structure
-
-- Analyzes existing asset structures
-
-- Fixes non-compliant asset trees
-
-### Create New Note
-
-```bash
-mkdocs-note new FILE_PATH [--template TEMPLATE_PATH]
-```
-
-- Creates a new note file with template content
-
-- Creates the corresponding asset directory
-
-- Validates asset tree structure compliance
-
-### Validate Structure
-
-```bash
-mkdocs-note validate [--path PATH]
-```
-
-- Checks if the asset tree structure complies with the plugin's design
-
-- Reports any structural issues
-
-### Template Management
-
-```bash
-mkdocs-note template [--check] [--create]
-```
+You can use the command line interface to manage your documentations and their assets correspondingly.
 
-- Check if the configured template file exists
-
-- Create the template file if it doesn't exist
-
-### Remove Note
-
-```bash
-mkdocs-note remove FILE_PATH [--keep-assets] [--yes]
-# or use the alias
-mkdocs-note rm FILE_PATH [--keep-assets] [--yes]
-```
-
-- Remove a note file and its corresponding asset directory
-
-- Use `--keep-assets` to keep the asset directory
-
-- Use `--yes` or `-y` to skip confirmation prompt
-
-### Clean Orphaned Assets
-
-```bash
-mkdocs-note clean [--dry-run] [--yes]
-```
-
-- Find and remove asset directories without corresponding note files
-
-- Use `--dry-run` to preview what would be removed without actually removing
-
-- Use `--yes` or `-y` to skip confirmation prompt
-
-- Automatically cleans up empty parent directories
-
-### Move/Rename Note or Directory
-
-```bash
-mkdocs-note move SOURCE DESTINATION [--keep-source-assets] [--yes]
-# or use the alias
-mkdocs-note mv SOURCE DESTINATION [--keep-source-assets] [--yes]
-```
-
-- **Mimics shell `mv` behavior**: 
-
-    - If destination doesn't exist: rename source to destination
-
-    - If destination exists and is a directory: move source into destination
-
-- Move or rename a note file or entire directory with its asset directories
-
-- Supports moving single notes or entire directories with all notes inside
-
-- Example: `mkdocs-note mv docs/notes/dsa/ds/trees docs/notes/dsa` moves to `docs/notes/dsa/trees`
-
-- Use `--keep-source-assets` to keep the source asset directory
-
-- Use `--yes` or `-y` to skip confirmation prompt
-
-- Automatically creates necessary parent directories
+## Overview
 
-- Cleans up empty parent directories in source location