Oliver Jakoubek e633fc2764 feat(bookstack-api-1us): write README with quick-start guide

Add comprehensive README with installation, authentication, usage
examples for all services, error handling, and available services table.

2026-01-30 09:56:19 +01:00

3 KiB

Raw Blame History

bookstack-api

A Go client library for the BookStack REST API. Zero external dependencies.

Installation

go get code.beautifulmachines.dev/jakoubek/bookstack-api

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    bookstack "code.beautifulmachines.dev/jakoubek/bookstack-api"
)

func main() {
    client, err := bookstack.NewClient(bookstack.Config{
        BaseURL:     "https://docs.example.com",
        TokenID:     os.Getenv("BOOKSTACK_TOKEN_ID"),
        TokenSecret: os.Getenv("BOOKSTACK_TOKEN_SECRET"),
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // List all books
    books, err := client.Books.List(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    for _, book := range books {
        fmt.Printf("%d: %s\n", book.ID, book.Name)
    }
}

Authentication

BookStack uses token-based authentication. Create an API token in your BookStack user profile under API Tokens.

Set the token ID and secret as environment variables:

export BOOKSTACK_TOKEN_ID="your-token-id"
export BOOKSTACK_TOKEN_SECRET="your-token-secret"

Usage

Search

results, err := client.Search.Search(ctx, "deployment guide", nil)
for _, r := range results {
    fmt.Printf("[%s] %s (score: %.1f)\n", r.Type, r.Name, r.Score)
}

Get a Page

page, err := client.Pages.Get(ctx, 42)
fmt.Println(page.HTML)

Export Page as Markdown

md, err := client.Pages.ExportMarkdown(ctx, 42)
fmt.Println(string(md))

Iterate All Books

Uses Go 1.23+ iterators for memory-efficient pagination:

for book, err := range client.Books.ListAll(ctx) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(book.Name)
}

Pagination and Filtering

pages, err := client.Pages.List(ctx, &bookstack.ListOptions{
    Count:  10,
    Offset: 0,
    Sort:   "-updated_at",
    Filter: map[string]string{"book_id": "1"},
})

Create and Update Pages

page, err := client.Pages.Create(ctx, &bookstack.PageCreateRequest{
    BookID:   1,
    Name:     "New Page",
    Markdown: "# Hello\n\nPage content here.",
})

page, err = client.Pages.Update(ctx, page.ID, &bookstack.PageUpdateRequest{
    Markdown: "# Updated\n\nNew content.",
})

Error Handling

page, err := client.Pages.Get(ctx, 999)
if errors.Is(err, bookstack.ErrNotFound) {
    fmt.Println("Page not found")
} else if errors.Is(err, bookstack.ErrUnauthorized) {
    fmt.Println("Invalid credentials")
}

Available Services

Service	Operations
`Books`	List, ListAll, Get
`Pages`	List, ListAll, Get, Create, Update, Delete, ExportMarkdown, ExportPDF
`Chapters`	List, ListAll, Get
`Shelves`	List, ListAll, Get
`Search`	Search
`Attachments`	List, Get, Create, Update, Delete
`Comments`	List, Get, Create, Update, Delete

Requirements

Go 1.23+
BookStack instance with API enabled

License

See LICENSE file.

3 KiB Raw Blame History