Skip to main content

Agent's Guide to Wiki

Agent Guide: Updating BookStack Wiki Pages

This guide outlines how AI agents can directly query, read, edit, and update pages in the self-hosted BookStack Wiki (https://wiki.drheck.dev/).

1. Golden Rules for Agents

🚨 MANDATORY RULE: READ LIVE CONTENT FIRST BEFORE EDITING

NEVER generate or overwrite page content from memory or scratch without first reading the current live page and its latest revisions. Humans frequently make live edits in the BookStack browser interface between agent turns. Overwriting a page without reading its latest markdown and page_revisions destroys user contributions, custom links, code blocks, and embedded images.

Every page update MUST follow this sequence:

  1. Fetch live markdown to a file via /home/luke/bin/read-bookstack-page <page_id> <output_file>.
  2. Query attached images from the images table.
  3. Incorporate existing content, user edits, and image tags into the updated document.
  4. Deploy changes with /home/luke/bin/update-bookstack-page <page_id> <file_path>.

🚨 ABSTRACT DATABASE-INTERNAL IDS FROM USER-FACING TEXT

Never include internal database IDs or object identifiers (e.g. Book 92, Page 100, page_id=31, image_id=45) in user-facing page bodies, changelogs, or documentation summaries. Database IDs are internal implementation details strictly for CLI helper execution (read-bookstack-page <id>, update-bookstack-page <id>). Humans navigate the wiki by title and URL slug. Always use human-readable titles, book names, and standard markdown hyperlinks (e.g. [Setup Detail](https://wiki.drheck.dev/books/setup-detail)), never raw numeric IDs.

🚨 DUAL STORAGE RULE (markdown vs html)

BookStack stores page source in the entity_page_data table:

  • markdown: Source text loaded by BookStack when a page is opened in the browser editor.
  • html: Rendered HTML displayed to public visitors on the website.

Never update html alone! Updating html alone causes the editor to load the outdated markdown column and wipe out HTML changes upon saving. Agents must update the markdown source via the official helper scripts.

2. Environment & Database Access

  • Service Host: ul (ul.drheck.dev)
  • Docker Container (Database): bookstack_db (MariaDB)
  • Docker Container (Web/App): bookstack
  • Env File: /data/docker/bookstack/.env
  • Database Name: bookstackapp

Note on Execution Context: The helper utilities interact directly with local Docker containers on ul. If the agent is running on another node (e.g. pikvm-studio or bmo95), execute helper commands over SSH to ul (e.g. ssh ul /home/luke/bin/find-bookstack-page <term>).

Official CLI utilities in /home/luke/bin/ on host ul eliminate shell quoting bugs, SQL newline escaping artifacts, and cache desync:

Step 1: Find Page ID or Book ID by Slug or Keyword

/home/luke/bin/find-bookstack-page <search_term>

Output:

id	name			slug			type
31	System Change log	system-change-log	page

Step 2: Export Live Markdown to a File (MANDATORY)

Export the live markdown directly to a clean file using the base64-safe reader:

/home/luke/bin/read-bookstack-page <page_id> /tmp/page_<page_id>.md

(Do NOT use raw mariadb -e "SELECT markdown..." queries, as the MariaDB CLI client escapes newlines into literal \n strings).

Step 3: Check Attached Images & Revisions

Check image attachments:

sudo docker exec bookstack_db mariadb \
  -ubookstack -p"$(grep DB_PASSWORD /data/docker/bookstack/.env | cut -d= -f2)" \
  bookstackapp -e "SELECT id, name, url FROM images WHERE uploaded_to=<page_id>;"

Step 4: Edit Content Locally in the File

Modify /tmp/page_<page_id>.md, ensuring that all existing user edits, links, and image references (![alt](url)) are preserved.

Step 5: Update Existing Page or Create New Page

To update an existing page:

/home/luke/bin/update-bookstack-page <page_id> /tmp/page_<page_id>.md

To create a new page in a book:

/home/luke/bin/create-bookstack-page <book_id> "<page_title>" <file_path>

These helpers Base64-encode content, invoke BookStack's native PHP PageContent models inside Docker (artisan tinker), compile both markdown and html columns, update revision tracking, and automatically clear the view cache.

Remember to clean up your temporary file afterwards (rm -f /tmp/page_<page_id>.md).

4. Verification

Verify that both markdown and html lengths and contents match:

sudo docker exec bookstack_db mariadb \
  -ubookstack -p"$(grep DB_PASSWORD /data/docker/bookstack/.env | cut -d= -f2)" \
  bookstackapp -e "SELECT page_id, LENGTH(markdown), LENGTH(html), LEFT(markdown, 150), LEFT(html, 150) FROM entity_page_data WHERE page_id=<page_id>\G"

5. Advanced Features & Typography Standards for Agents

BookStack on ul is enhanced with rich typographical, mathematical, and layout capabilities. Agents are encouraged to leverage these features:

5.1 KaTeX TeX Mathematical Engine (Globally Enabled)

A client-side KaTeX rendering engine is active across all wiki pages.

  • Display Equations (Block Math): Enclose in $$ ... $$ on their own lines: 
    $$\text{FREQ} = \frac{433,920,000}{24,000,000} \times 2^{16} = 1,184,883 = \mathbf{0x121473}$$
  • Inline Math: Enclose in single $ ... $ directly within sentences: $T_e = 291.27\text{ }\mu\text{s}$
  • Signal Chains & Matrices: Use standard LaTeX macros like \longrightarrow, \begin{pmatrix}...\end{pmatrix}, \begin{cases}...\end{cases}, \int, and \sum.
  • Subscript / Underscore Safety: Do not put multiple unescaped underscores on the same line in LaTeX (e.g. \text{DRATE_M}...\text{DRATE_E}), as CommonMark will interpret them as Markdown italics (<em>...</em>). Use hyphens (e.g. \text{DRATE-M}) or explicit math subscripts (x_1).
  • No Backslash-Punctuation Spacing Macros (\;, \,, \!): Never use backslash-punctuation spacing commands inside Markdown math blocks. BookStack's server-side CommonMark parser strips backslashes before ASCII punctuation characters prior to client-side KaTeX rendering, turning \; into a literal ; and \, into a literal ,. Always use alphabetic TeX spacing macros (\quad, \qquad) or rely on built-in relation spacing around \longrightarrow.

5.2 Native BookStack Callout Banners

Use BookStack's native HTML callout classes for colored, professional alert callouts:

<p class="callout info"><strong>Info Note:</strong> Background context and operational instructions.</p>
<p class="callout success"><strong>Success:</strong> Empirical tests verified with zero errors.</p>
<p class="callout warning"><strong>Warning:</strong> Ensure Word Clock is 75Ω terminated on the final device.</p>
<p class="callout danger"><strong>Danger / Critical:</strong> Never run recursive find commands on host ul.</p>

5.3 Japanese Typography & Furigana (Ruby Text)

HTML5 Ruby annotations are fully supported in page bodies:

  • Whole-word Furigana: <ruby>漢字<rt>かんじ</rt></ruby>
  • Per-character Furigana: <ruby>振<rt>ふ</rt>り<rt></rt>仮<rt>が</rt>名<rt>な</rt></ruby>
  • Japanese in TeX Math: $$\text{周波数 } f = 433.92\text{ MHz}$$

5.4 Collapsible Accordions (<details>)

Use collapsible details to tuck away long raw data logs, register dumps, or secondary tables:

<details>
  <summary><strong>Click to expand technical registers</strong></summary>
  <p>Detailed register addresses and bitfield descriptions go here.</p>
</details>

5.5 High-Resolution Gallery Images with Lightbox Links

To embed images stored in the BookStack gallery with centering, scaling, and lightbox popup support:

<p align="center">
  <a href="https://wiki.drheck.dev/uploads/images/gallery/YYYY-MM/image-name.jpg" target="_blank">
    <img src="https://wiki.drheck.dev/uploads/images/gallery/YYYY-MM/image-name.jpg" alt="Description" width="65%" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15); display: block; margin: 0 auto;">
  </a>
  <em style="display: block; text-align: center; margin-top: 6px; font-size: 0.9em; color: #666;">Figure 1: Descriptive caption.</em>
</p>

5.6 Comprehensive Capabilities Reference

For an exhaustive cheat sheet, math examples, and live test cases, refer to: 📖 Meta: Wiki Capabilities, TeX Math & Typography Reference

6. Critical Operational Gotchas for Agents

  1. Never Expose Internal Database IDs in Documentation: Do not write Book 92, Page 100, or page_id=31 in user-facing text, changelogs, or documentation summaries. Always use human-readable titles and standard hyperlinks.
  2. Never Parse SQL Output via Shell Strings: Always use /home/luke/bin/read-bookstack-page and /home/luke/bin/update-bookstack-page. Ad-hoc mariadb queries introduce character escaping artifacts on \n, \t, and \.
  3. Strip Top-Level # <Page Title> Headers: BookStack renders the page title as an <h1> header automatically. Strip # <Page Title> from markdown source to prevent duplicate headers.
  4. Preserve Attached Images: Always check for image links before overwriting.
  5. Docker Working Directory (-w /app/www): Always include -w /app/www when running artisan inside the container.
  6. Avoid \;, \,, and \! in KaTeX Equations: CommonMark unescapes \<punctuation> into literal punctuation before KaTeX runs; use alphabetic macros (\quad, \qquad) instead.