PHPackages aichadigital/bookstack-sync - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Parsing & Serialization](/categories/parsing) 4. / 5. aichadigital/bookstack-sync ActiveLibrary[Parsing & Serialization](/categories/parsing) aichadigital/bookstack-sync =========================== Laravel package for synchronizing Markdown documentation with BookStack wiki v1.0.0(4mo ago)066↓100%[2 PRs](https://github.com/AichaDigital/bookstack-sync/pulls)AGPL-3.0-or-laterPHPPHP ^8.2CI passing Since Dec 14Pushed 1mo agoCompare [ Source](https://github.com/AichaDigital/bookstack-sync)[ Packagist](https://packagist.org/packages/aichadigital/bookstack-sync)[ Docs](https://github.com/aichadigital/bookstack-sync)[ RSS](/packages/aichadigital-bookstack-sync/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (17)Versions (6)Used By (0) BookStack Sync ============== [](#bookstack-sync) [![Latest Version on Packagist](https://camo.githubusercontent.com/e9007e667433463ac1784270c99c6cff6fabe6f0523bb3f1cf992f871559a4e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61696368616469676974616c2f626f6f6b737461636b2d73796e632e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aichadigital/bookstack-sync)[![Total Downloads](https://camo.githubusercontent.com/2902b5f7d6ddcbf14197d698282a6c5d591ec4973a64a90f26e73bbe8cd34503/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61696368616469676974616c2f626f6f6b737461636b2d73796e632e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aichadigital/bookstack-sync)[![GitHub Tests Action Status](https://camo.githubusercontent.com/5e81ba431a8a99ef4bb5b77d2fd0cb9745b6feb52afbfe17d840b6276c2de78e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f41696368614469676974616c2f626f6f6b737461636b2d73796e632f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/AichaDigital/bookstack-sync/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/2a9a2c573b2905fa6dadf0ade83ad8d08ac78d05edd5d52ee65007df85d02ecf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f41696368614469676974616c2f626f6f6b737461636b2d73796e632f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/AichaDigital/bookstack-sync/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![PHPStan Level 8](https://camo.githubusercontent.com/fff00cebb924e124a7335e6bd8ca8f8cf38869463c1654eff45d0939f1f21c57/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![codecov](https://camo.githubusercontent.com/c54aba931246f86aa916201611711cf27663c79ff74bfbbb52bfa2e5d8e94901/68747470733a2f2f636f6465636f762e696f2f67682f41696368614469676974616c2f626f6f6b737461636b2d73796e632f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/AichaDigital/bookstack-sync)[![PHP Version](https://camo.githubusercontent.com/1bbbac5cce10120bc7592396fb95f13b2a22dee817461f3b9fe23d7dbad7f694/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f61696368616469676974616c2f626f6f6b737461636b2d73796e632e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/aichadigital/bookstack-sync)[![Laravel Version](https://camo.githubusercontent.com/b7712503a0194afa291f0817bae0e2d08356a3d6fa4ae1dd7c6273232f957079/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e7825323025374325323031312e7825323025374325323031322e782d7265642e7376673f7374796c653d666c61742d737175617265)](https://laravel.com)[![License](https://camo.githubusercontent.com/c0e359d8331ccb0c91f4d34ace6f6df33b8177e75de78692684bd89f5c66c166/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4147504c2d2d332e302d2d6f722d2d6c617465722d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE.md) A Laravel package for synchronizing Markdown documentation with [BookStack](https://www.bookstackapp.com/) wiki. Perfect for keeping your project documentation in sync between your codebase and BookStack. Features -------- [](#features) - **Bidirectional Sync**: Push local Markdown files to BookStack or pull BookStack content to local files - **Local SQLite Cache**: Reduces API calls by caching wiki structure locally with change detection - **Bookmark Conversion**: Automatically converts AI-generated bookmarks (Claude, Cursor, etc.) to BookStack's URL-encoded format - **Spanish Character Support**: Full support for UTF-8 characters (á, é, í, ó, ú, ñ, ç, ü, etc.) - **Artisan Commands**: Easy-to-use CLI commands for all operations - **Conflict Resolution**: Multiple strategies for handling sync conflicts - **Dry Run Mode**: Preview changes before making them Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10, 11, or 12 - BookStack instance with API access Installation ------------ [](#installation) ``` composer require aichadigital/bookstack-sync --dev ``` Publish the configuration file: ``` php artisan vendor:publish --tag="bookstack-sync-config" ``` Configuration ------------- [](#configuration) Add these variables to your `.env` file: ``` BOOKSTACK_URL=https://your-bookstack-instance.com/ BOOKSTACK_TOKEN_ID=your-token-id BOOKSTACK_TOKEN_SECRET=your-token-secret # Optional defaults BOOKSTACK_BOOK_ID=123 BOOKSTACK_MARKDOWN_PATH=docs ``` Alternative variable names are also supported for compatibility: ``` WIKI_URL=https://your-bookstack-instance.com/ WIKI_TOKEN_ID=your-token-id WIKI_TOKEN=your-token-secret ``` Usage ----- [](#usage) ### Artisan Commands [](#artisan-commands) #### Check Connection Status [](#check-connection-status) ``` php artisan bookstack:status php artisan bookstack:status --books php artisan bookstack:status --shelves ``` #### Push Local Files to BookStack [](#push-local-files-to-bookstack) ``` # Push docs directory to book ID 5 php artisan bookstack:push docs --book=5 # Dry run (preview without changes) php artisan bookstack:push docs --book=5 --dry-run # Skip confirmation php artisan bookstack:push docs --book=5 --force ``` #### Pull from BookStack to Local Files [](#pull-from-bookstack-to-local-files) ``` # Pull book ID 5 to local directory php artisan bookstack:pull --book=5 --path=docs # Dry run php artisan bookstack:pull --book=5 --path=docs --dry-run ``` #### Export Content [](#export-content) ``` # Export as Markdown php artisan bookstack:export page 123 # Export book as PDF php artisan bookstack:export book 5 --format=pdf --output=manual.pdf # Available formats: markdown, html, pdf, plaintext ``` #### Search [](#search) ``` php artisan bookstack:search "configuration" php artisan bookstack:search "instalación" --limit=50 ``` #### Sync Wiki Structure to Local Cache [](#sync-wiki-structure-to-local-cache) ``` # Sync all wiki structure to local SQLite database php artisan bookstack:sync # Fresh sync (deletes existing database first) php artisan bookstack:sync --fresh # Sync only specific entities php artisan bookstack:sync --no-shelves --no-chapters ``` #### Query Local Cache [](#query-local-cache) ``` # Show database statistics php artisan bookstack:db stats # List cached entities php artisan bookstack:db shelves php artisan bookstack:db books php artisan bookstack:db chapters --book=5 php artisan bookstack:db pages --book=5 --chapter=10 # Include deleted items php artisan bookstack:db pages --deleted # Show database path and size php artisan bookstack:db path # Delete local database php artisan bookstack:db delete --force ``` ### Programmatic Usage [](#programmatic-usage) ``` use AichaDigital\BookStackSync\Facades\BookStackSync; // List all books $books = BookStackSync::books(); // Get a specific page $page = BookStackSync::page(123); // Create a new page with Markdown content $page = BookStackSync::createPage( bookId: 5, name: 'Configuración Inicial', content: '# Introducción\n\nContenido aquí...', chapterId: 10 ); // Search $results = BookStackSync::search('instalación'); // Sync operations $result = BookStackSync::pushToBook('/path/to/docs', 5); $result = BookStackSync::pullFromBook(5, '/path/to/docs'); ``` ### Bookmark Conversion [](#bookmark-conversion) The package automatically handles the conversion between AI-generated bookmark formats and BookStack's URL-encoded format: ``` use AichaDigital\BookStackSync\Facades\BookStackSync; // Encode for BookStack $encoded = BookStackSync::encodeBookmark('sección-principal'); // Returns: secci%C3%B3n-principal // Decode from BookStack $decoded = BookStackSync::decodeBookmark('secci%C3%B3n-principal'); // Returns: sección-principal ``` ### Direct Parser Usage [](#direct-parser-usage) ``` use AichaDigital\BookStackSync\Parsers\MarkdownParser; $parser = new MarkdownParser(); // Convert content for BookStack $content = '# Introducción\n\nSee [sección](#sección) for details.'; $converted = $parser->parseForBookStack($content); // Anchors are now URL-encoded // Extract headings $headings = $parser->extractHeadings($content); // Generate Table of Contents $toc = $parser->generateTableOfContents($content); ``` Markdown Frontmatter -------------------- [](#markdown-frontmatter) You can use YAML frontmatter in your Markdown files to specify metadata: ``` --- title: Mi Página chapter: Introducción --- # Content here... ``` Supported frontmatter fields: - `title` / `name`: Page title (overrides filename) - `chapter`: Chapter name (creates if doesn't exist) - `bookstack_id`: Links to existing BookStack page for updates Sync Configuration ------------------ [](#sync-configuration) Configure sync behavior in `config/bookstack-sync.php`: ``` 'sync' => [ // Direction: 'push', 'pull', or 'bidirectional' 'direction' => env('BOOKSTACK_SYNC_DIRECTION', 'push'), // Conflict resolution: 'local', 'remote', 'newest', 'manual' 'conflict_resolution' => env('BOOKSTACK_CONFLICT_RESOLUTION', 'manual'), // Auto-create missing structure 'auto_create_structure' => true, // Dry run mode 'dry_run' => false, ], ``` Local Database Configuration ---------------------------- [](#local-database-configuration) The package includes a local SQLite cache to reduce API calls and enable change detection: ``` 'database' => [ // Enable/disable local database caching 'enabled' => env('BOOKSTACK_LOCAL_DB', true), // Database path (relative to storage/ or absolute path) 'path' => env('BOOKSTACK_DB_PATH', 'bookstack-sync.sqlite'), ], ``` ### Environment Variables [](#environment-variables) ``` # Enable local SQLite cache (default: true) BOOKSTACK_LOCAL_DB=true # Custom database path (default: storage/bookstack-sync.sqlite) BOOKSTACK_DB_PATH=bookstack-sync.sqlite ``` ### How It Works [](#how-it-works) 1. Run `php artisan bookstack:sync` to populate the local cache 2. The cache stores all shelves, books, chapters, and pages with their metadata 3. During push/pull operations, the package uses content hashes to skip unchanged files 4. Deleted items in BookStack are marked with `is_deleted` flag for tracking Spanish Character Encoding Reference ------------------------------------ [](#spanish-character-encoding-reference) CharacterURL Encodedá%C3%A1é%C3%A9í%C3%ADó%C3%B3ú%C3%BAñ%C3%B1ü%C3%BCç%C3%A7Testing ------- [](#testing) ``` composer test ``` To run tests against your actual BookStack instance, copy `.env.example` to `.env` and configure your credentials: ``` cp .env.example .env # Edit .env with your BookStack credentials composer test ``` API Reference ------------- [](#api-reference) This package uses the [BookStack REST API](https://demo.bookstackapp.com/api/docs). Key endpoints used: - `/api/shelves` - Shelf operations - `/api/books` - Book operations - `/api/chapters` - Chapter operations - `/api/pages` - Page operations - `/api/search` - Search across content Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [AichaDigital](https://github.com/aichadigital) - [All Contributors](../../contributors) Special thanks to: - [BookStack](https://www.bookstackapp.com/) - The excellent open-source wiki platform that this package integrates with - [Dan Brown](https://github.com/ssddanbrown) - Creator and maintainer of BookStack > **Trademark Notice**: BookStack® is a registered trademark of Daniel Brown. This package is not affiliated with, endorsed by, or sponsored by BookStack or Daniel Brown. License ------- [](#license) This package is licensed under the **GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)**. Please see [License File](LICENSE.md) for more information. ### Health Score 42 — FairBetter than 89% of packages Maintenance90 Actively maintained with recent releases Popularity11 Limited adoption so far Community8 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 93.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~5 days Total 3 Last Release 135d ago Major Versions v0.9.1 → v1.0.02025-12-25 ### Community Maintainers ![](https://www.gravatar.com/avatar/0a4694c48c325d3dfbc4c43d97c2617f9317d7a447971750c338f943a88bd164?d=identicon)[abkrim](/maintainers/abkrim) --- Top Contributors [![abkrim](https://avatars.githubusercontent.com/u/1238625?v=4)](https://github.com/abkrim "abkrim (14 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") --- Tags laraveldocumentationmarkdownwikisyncAichaDigitalBookStack ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/aichadigital-bookstack-sync/health.svg) ``` [![Health](https://phpackages.com/badges/aichadigital-bookstack-sync/health.svg)](https://phpackages.com/packages/aichadigital-bookstack-sync) ``` ### Alternatives [laravel/socialite Laravel wrapper around OAuth 1 & OAuth 2 libraries. 5.7k96.9M672](/packages/laravel-socialite)[spatie/laravel-health Monitor the health of a Laravel application 85810.0M83](/packages/spatie-laravel-health)[simplestats-io/laravel-client Client for SimpleStats! 4515.5k](/packages/simplestats-io-laravel-client)[dniccum/nova-documentation A Laravel Nova tool that allows you to add markdown-based documentation to your administrator's dashboard. 37116.4k](/packages/dniccum-nova-documentation)[spatie/laravel-markdown-response Serve markdown versions of your HTML pages to AI agents and bots 6512.6k](/packages/spatie-laravel-markdown-response)[musahmusah/laravel-multipayment-gateways A Laravel Package that makes implementation of multiple payment Gateways endpoints and webhooks seamless 852.2k1](/packages/musahmusah-laravel-multipayment-gateways) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)