guidebook 0.1.12

HonKit/GitBook compatible static book generator
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# CLAUDE.md - guidebook

A static site generator compatible with HonKit/GitBook.

## Project Overview

- **Language:** Rust
- **Published to:** crates.io (`cargo install guidebook`)
- **Repository:** https://github.com/guide-inc-org/guidebook

## Build & Test

```bash
# Build
cargo build --release

# Test
cargo test

# Build documentation locally
./target/release/guidebook build

# Start dev server
./target/release/guidebook serve
```

## Release Procedure

1. Update version in `Cargo.toml`
2. Commit & push
3. Create and push tag (binary is auto-generated to GitHub Releases)
4. Publish to crates.io

```bash
# After version update
git add -A && git commit -m "Bump version to vX.Y.Z"
git push origin main

# Create & push tag (triggers release workflow)
git tag vX.Y.Z
git push origin vX.Y.Z

# Publish to crates.io
cargo publish
```

## Directory Structure

```
src/
├── main.rs          # CLI entry point
├── builder/
│   ├── mod.rs       # Build process
│   ├── renderer.rs  # Markdown to HTML conversion
│   └── template.rs  # HTML template
├── parser/
│   ├── mod.rs
│   ├── book_config.rs  # book.json parser
│   ├── langs.rs        # LANGS.md parser (multi-language support)
│   └── summary.rs      # SUMMARY.md parser
templates/
├── gitbook.css      # Stylesheet
├── gitbook.js       # Client-side JS
├── collapsible.js   # Collapsible sections
└── search.js        # Search functionality
```

## Important Design Decisions

### Do NOT use `<base>` tag

**Reason:** Using `<base href>` causes relative image paths in markdown (e.g., `../../../assets/...`) to resolve from base, breaking when deployed to subdirectories.

**Solution:** Embed `root_path` directly into CSS/JS/links (same approach as HonKit)

## CI/CD

### Release Workflow

`.github/workflows/release.yml` - Publishes Linux binary to GitHub Releases on tag push.

Consumers download pre-built binary:
```yaml
- name: Install guidebook
  run: |
    curl -sL https://github.com/guide-inc-org/guidebook/releases/latest/download/guidebook-linux-x86_64.tar.gz | tar xz
    ./guidebook build
```

## Changelog

- **2025-12-25 v0.1.12:** Fix SPA navigation URL accumulation bug
- **2025-12-25 v0.1.10:** Fix image paths (remove `<base>` tag), add release workflow