You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For more details, please refer to the [Installation | User Guide](usage/installation.md).
28
28
29
-
## Configuration
30
-
31
-
### Basic Configuration
32
-
33
-
For basic configuration, you can add the following to your `mkdocs.yml`:
34
-
35
-
```yml
36
-
plugins:
37
-
- mkdocs-note
38
-
```
39
-
40
-
It's the simplest configuration, and the plugin will use the default configuration.
29
+
## Use CLI to manage notes
41
30
42
-
### Recommended Configuration
31
+
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**.
43
32
44
-
For recommended configuration, you can add the following to your `mkdocs.yml`:
33
+
### Create a note
45
34
46
-
```yml
47
-
plugins:
48
-
- mkdocs-note:
49
-
notes_dir: "docs/notes"
50
-
index_file: "docs/index.md"
51
-
start_marker: "<!-- recent_notes_start -->"
52
-
end_marker: "<!-- recent_notes_end -->"
53
-
max_notes: 10
54
-
supported_extensions: [".md"]
55
-
```
56
-
57
-
In general, Mkdocs Note supports highly customizable configuration, you can configure the plugin to your own needs.
58
-
59
-
Please refer to the [Configuration Options | User Guide](usage/config.md) for more details about the information of each configuration options.
60
-
61
-
## Create Your Note Boxes
62
-
63
-
### Manual Setup
64
-
65
-
1. Create the notes directory you have just configured above in your mkdocs project (e.g., `docs/notes`)
66
-
67
-
2. Create an `index.md` file in your notes directory manually.
68
-
69
-
3. Add the marker comments to your index file:
70
-
71
-
```markdown
72
-
# My Notes
73
-
74
-
<!-- recent_notes_start -->
75
-
<!-- recent_notes_end -->
35
+
To create a note, you can use the following command:
36
+
```bash
37
+
mkdocs-note new /path/to/note
76
38
```
77
39
78
-
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.
79
-
80
-
### Use CLI Commands
81
-
82
-
The plugin provides several CLI commands for docs and their assets management.
83
-
84
-
And first of all, this is a mkdocs-based plugin, so you need to have a mkdocs project first.
85
-
86
-
#### Validate Structure
40
+
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.
87
41
88
-
Use following command to validate the structure of your docs and assets:
42
+
### Remove Note or Note Directory
89
43
44
+
To remove a note, you can use the following command:
90
45
```bash
91
-
mkdocs-note validate [--path PATH]
46
+
mkdocs-note remove /path/to/note-or-directory
92
47
```
93
48
94
-
This command will check if the structure of your docs and assets is compliant with the plugin's design.
49
+
It will remove the note or note directory and the corresponding asset directory(ies) from the `assets` directory, inspired by shell command `rm -rf`.
95
50
96
-
If there are any issues, it will report them to you.
97
-
98
-
#### Initialize Docs and Assets Structure
99
-
100
-
Use following command to initialize your mkdocs-based docs and assets structure:
51
+
### Move or Rename Note or Note Directory
101
52
53
+
To move or rename a note or note directory, you can use the following command:
If your docs already has a structure, this command will analyze the existing asset structures and fix the non-compliant asset trees.
107
-
108
-
However, it will not help you move your existing assets to the new structure.
109
-
110
-
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/`.
58
+
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`.
111
59
112
-
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.
60
+
More details, please refer to the [CLI Commands | User Guide](usage/cli.md).
113
61
114
-
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.
62
+
## Configuration
115
63
116
-
#### Create New Documentation
64
+
###Basic Configuration
117
65
118
-
Use following command to create a new documentation:
66
+
For basic configuration, you can add the following to your `mkdocs.yml`:
119
67
120
-
```bash
121
-
mkdocs-note new FILE_PATH
68
+
```yml
69
+
plugins:
70
+
- mkdocs-note
122
71
```
123
72
124
-
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.
73
+
It's the simplest configuration, and the plugin will use the default configuration.
125
74
126
-
#### Remove Existing Documentation
75
+
### Recommended Configuration
127
76
128
-
Use following command to remove an existing documentation:
77
+
To use the plugin in a recommended way, you can add the following to your `mkdocs.yml`:
129
78
130
-
```bash
131
-
mkdocs-note remove FILE_PATH
79
+
```yml
80
+
plugins:
81
+
- mkdocs-note:
82
+
recent_notes_config:
83
+
enabled: true
84
+
insert_marker: "<!-- recent_notes -->"
85
+
insert_num: 5
86
+
graph_config:
87
+
enabled: true
88
+
name: "title"
89
+
debug: false
132
90
```
133
91
134
-
This command will remove the documentation file and its corresponding asset directory, and before doing that, it will ask you for confirmation.
135
-
136
-
And you can use the alias `mkdocs-note rm` to do the same thing.
137
-
138
-
#### Other Commands
92
+
## Recent Notes Insertion
139
93
140
-
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.
94
+
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:
141
95
142
-
#### Configuration Auto-Loading
143
-
144
-
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:
145
-
146
-
```bash
147
-
mkdocs-note --config path/to/mkdocs.yml <command>
96
+
```yml
97
+
plugins:
98
+
- mkdocs-note:
99
+
recent_notes_config:
100
+
enabled: true
101
+
insert_marker: "<!-- recent_notes -->"
102
+
insert_num: 5
148
103
```
149
104
150
-
## Getting Help
151
-
152
-
See the [User Guide](usage/index.md) for more details about the usage and features of the plugin.
153
-
154
-
This project is still in its infancy stage, so any feedback or suggestions are welcome.
155
-
156
-
You can open an issue on [GitHub](https://github.com/virtualguard101/mkdocs-note/issues) to report bugs or request features.
157
-
158
-
Or you can email me directly at [virtualguard101@gmail.com](mailto:virtualguard101@gmail.com), though I may respone late because of my busy schedule.
159
-
160
-
Thank you for using MkDocs Note!
105
+
More details, please refer to the [Recent Notes Insertion | User Guide](usage/recent-notes.md).
Copy file name to clipboardExpand all lines: docs/usage/cli.md
+4-133Lines changed: 4 additions & 133 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,143 +2,14 @@
2
2
date: 2025-10-17 10:58:59
3
3
title: Command Line Interface
4
4
permalink:
5
-
publish: true
5
+
publish: false
6
6
---
7
7
8
8
# Command Line Interface
9
9
10
-
`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.
10
+
`mkdocs-note` provides a command line interface for documentation management.
11
11
12
-
## Overview
13
-
14
-
| Command | Description |
15
-
|---------|-------------|
16
-
|`mkdocs-note init`| Initialize the notes directory structure |
17
-
|`mkdocs-note new`| Create a new note file with template content |
18
-
|`mkdocs-note validate`| Validate the asset tree structure |
19
-
|`mkdocs-note template`| Manage the template file |
20
-
|`mkdocs-note remove`/`rm`| Remove a note file and its corresponding asset directory |
21
-
|`mkdocs-note clean`| Clean orphaned assets |
22
-
|`mkdocs-note move`/`mv`| Move or rename a note file or directory |
23
-
24
-
For overview in command line, you can use the `--help/-h` option to get the help information of all commands.
25
-
```bash
26
-
mkdocs-note --help
27
-
# Or
28
-
mkdocs-note -h
29
-
```
30
-
31
-
For detailed information of a specific command, you can use the `mkdocs-note <command> --help` command to get the help information of a command.
32
-
```bash
33
-
mkdocs-note <command> --help
34
-
```
35
-
36
-
## Configuration Auto-Loading
37
-
38
-
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:
39
-
40
-
```bash
41
-
mkdocs-note --config path/to/mkdocs.yml <command>
42
-
```
43
-
44
-
## Commands Details
45
-
46
-
### Initialize Notes Directory
47
-
48
-
```bash
49
-
mkdocs-note init [--path PATH]
50
-
```
51
-
52
-
- Creates the docs and assets directory structure
53
-
54
-
- Analyzes existing asset structures
55
-
56
-
- Fixes non-compliant asset trees
57
-
58
-
### Create New Note
59
-
60
-
```bash
61
-
mkdocs-note new FILE_PATH [--template TEMPLATE_PATH]
62
-
```
63
-
64
-
- Creates a new note file with template content
65
-
66
-
- Creates the corresponding asset directory
67
-
68
-
- Validates asset tree structure compliance
69
-
70
-
### Validate Structure
71
-
72
-
```bash
73
-
mkdocs-note validate [--path PATH]
74
-
```
75
-
76
-
- Checks if the asset tree structure complies with the plugin's design
77
-
78
-
- Reports any structural issues
79
-
80
-
### Template Management
81
-
82
-
```bash
83
-
mkdocs-note template [--check] [--create]
84
-
```
12
+
You can use the command line interface to manage your documentations and their assets correspondingly.
0 commit comments