aRustyDev / aRustyDev/gh

feat: Add `mdbook` action

Open
#6 0 comments 0 reactions 0 assignees View on GitHub
enhancement new-action
Dominant language
Shell
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Create a reusable GitHub Action to run mdbook commands with plugin support.

## Use Case

Build and test mdbook documentation projects. Expects mdbook to be pre-installed but handles plugin installation.

## Specification

### Inputs

| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `command` | Yes | — | `build`, `test`, or `serve` |
| `book_dir` | No | `.` | Directory containing book.toml |
| `plugins` | No | — | Comma-separated list of plugins to install |
| `dest_dir` | No | — | Override output directory |

### Example Usage

```yaml
- uses: arustydev/gha/mdbook@v1
with:
command: build
plugins: mermaid, toc, admonish

- uses: arustydev/gha/mdbook@v1
with:
command: test
```

## Implementation Notes

### Plugin Handling

- Plugins installed via `cargo install mdbook-{plugin}`
- Common plugins: `mermaid`, `toc`, `admonish`, `linkcheck`, `katex`
- Cache plugin binaries for faster subsequent runs

### Pre-requisites

- Expects `mdbook` binary to be available in PATH
- Expects `cargo` to be available for plugin installation
- Workflow should install mdbook before this action runs

### Commands

```bash
# Build
mdbook build "$book_dir" --dest-dir "$dest_dir"

# Test
mdbook test "$book_dir"

# Serve (primarily for local dev, less useful in CI)
mdbook serve "$book_dir"
```

## Related

- Part of docs aggregation workflow extraction
- Used after `sparse-checkout-aggregate` and `symlink-map` actions

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.