bookstack-api – Go-Client für die BookStack REST API

bookstack-api ist eine Go-Bibliothek für den Zugriff auf die BookStack REST API. Die Library hat keine externen Abhängigkeiten und nutzt moderne Go-Features wie Iteratoren (Go 1.23+).

Was ist BookStack?

BookStack ist eine beliebte Open-Source-Plattform für Dokumentation und Wissensmanagement. Mit über 18.000 GitHub-Stars ist es eine der populärsten Self-Hosted-Wiki-Lösungen. Die Inhalte werden in einer dreistufigen Hierarchie organisiert: Regale → Bücher → Kapitel → Seiten.

Warum diese Library?

Ich nutze BookStack für interne Dokumentation und wollte Inhalte programmatisch erstellen und aktualisieren können – zum Beispiel für automatisierte Statusberichte oder die Synchronisation von Dokumentation aus anderen Quellen.

Installation

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

Authentifizierung

BookStack verwendet Token-basierte Authentifizierung. Erstellen Sie einen API-Token in Ihrem BookStack-Benutzerprofil unter API Tokens.

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

Schnellstart

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()

    // Alle Bücher auflisten
    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)
    }
}

Weitere Beispiele

Volltextsuche

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

Seite als Markdown exportieren

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

Neue Seite erstellen

page, err := client.Pages.Create(ctx, &bookstack.PageCreateRequest{
    BookID:   1,
    Name:     "Neue Seite",
    Markdown: "# Überschrift\n\nInhalt der Seite.",
})

Alle Bücher durchiterieren

Die Library nutzt Go 1.23+ Iteratoren für speichereffiziente Pagination:

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

Verfügbare Services

Service	Operationen
`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

Voraussetzungen

Go 1.23 oder höher
BookStack-Instanz mit aktivierter API

Lizenz

MIT License – siehe LICENSE.