https://github.com/mcmah309/mdbook-tools
A flexible CLI tool for organizing files and creating mdBooks
https://github.com/mcmah309/mdbook-tools
cli mdbook rust
Last synced: 4 months ago
JSON representation
A flexible CLI tool for organizing files and creating mdBooks
- Host: GitHub
- URL: https://github.com/mcmah309/mdbook-tools
- Owner: mcmah309
- License: mit
- Created: 2023-12-16T10:33:01.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-08T10:24:07.000Z (over 1 year ago)
- Last Synced: 2025-06-25T08:03:06.240Z (4 months ago)
- Topics: cli, mdbook, rust
- Language: Rust
- Homepage:
- Size: 220 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mdbook-tools
[](https://crates.io/crates/mdbook-tools)
[](https://opensource.org/licenses/MIT)
`mdbook-tools` is a flexible cli tool for organizing files and creating [mdBooks](https://github.com/rust-lang/mdBook). Combining `mdbook-tools` and `mdbook` allows you to embed documentaion directly into your project structure or maintain a completely seperate set of documentation or notes. The result is you are able to generate and maintian a concise book.
### Example Using mdbook-tools To Maintain Notes
For a directory structure like
```
...
├── python
│ ├── 01_venv.md
│ ├── 02_pip_vs_python_-m_pip.md
│ ├── 03_venv.md
│ ...
│ └── README.md
├── rust
│ ├── 01_borrowing_and_ownership.md
│ ├── 02_references_and_pointers.md
│ ├── 03_lifetimes.md
│ ├── 04_cargo.md
│ ├── 05_print_and_format.md
│ ├── 06_pinning,_moving_(&_memory),_copying.md
│ ├── 07_tokio.md
│ ├── 08_tower.md
│ ...
│ └── README.md
...
```
Running
```bash
mdbook-tools summary --include-unnumbered-directories
mdbook serve
```
Will give you:
### CLI Preview
```
mdbook tools for organizing books.
Usage: mdbook-tools
Commands:
summary
The 'summary' command automates the generation of a structured summary file.
It sequentially reads numbered md files and directories (e.g., "0001_") to define their order in the summary.
If any md files or directories do not have a number, they are ignored by default.
Directories use their 'README.md' file to define their content in the summary. As such, directories without a 'README.md' are ignored,
but the descendants are still searched.
Numbering resets for each directory, reflecting their hierarchical structure in the summary.
'README.md' files are exempt from numbering.
Section headers are created by removing underscores and capitalizing the first letter of each word.
Section names exclude numeric prefixes.
mv
The 'mv' command facilitates reorganizing md files or directories within the book's structure.
It allows moving a file or directory to a specified position (index) in a different directory.
The index numbering starts at 1, with 'README.md' is exempt.
When a file is moved to an occupied index, the existing file or directory, and those following it,
are automatically shifted down to accommodate the new file or directory, and the original directory is updated as well.
Summary is not updated.
re-order
Re-orders all the existing files in the path. Any gaps in the current order are collapsed and the new level is applied.
e.g. ["001_..", "003_.."] for level 2 becomes ["01_", "02_"].
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
### Install
```bash
cargo install mdbook-tools
```
### Useful Bash Commands For Migration Over To mdbook-tools
Replace all spaces in files and directories (including sub-directories) names with underscore
```bash
find . -depth -name '* *' -execdir bash -c 'mv "$1" "${1// /_}"' bash {} \;
```
Rename every file and directory to their lowercase equivalent, recursively.
```bash
find . -depth -exec bash -c '
for item; do
dir=$(dirname "$item")
base=$(basename "$item")
lower=$(echo "$base" | tr '[:upper:]' '[:lower:]')
if [ "$base" != "$lower" ]; then
mv -T "$item" "$dir/$lower"
fi
done
' bash {} +
```