Confluence HTML to BookStack

PowerShell tools to convert a Confluence HTML export into BookStack pages.

The scripts are numbered in the order you run them:

API/
  _1_prepare-confluence-html-for-bookstack.ps1
  _2_fix-bookstack-hyperlinks.ps1
  _3_import-ready-bookstack.ps1
  bookstack-config.example.json

What It Does

• Converts exported Confluence HTML pages into cleaner BookStack-ready HTML.
• Embeds local Confluence attachment images into the HTML.
• Lets you organize pages into folders before import.
• Converts folders into BookStack chapters.
• Fixes internal Confluence links after the files are organized.
• Imports the pages into BookStack through the BookStack API.

Requirements

• PowerShell.
• A Confluence HTML space export.
• A BookStack API token.
• Access to the target BookStack book.

Setup

Copy the example config:

Copy-Item .\API\bookstack-config.example.json .\API\bookstack-config.json

Edit API\bookstack-config.json and set:

• BaseUrl
• BookUrl
• BookSlug
• TokenId
• TokenSecret
• ReadyDir

Keep DeleteAfterImport set to false until you have tested the import.

Do not commit bookstack-config.json. It contains local paths and API secrets.

Workflow

Run commands from the project root.

1. Prepare The HTML

.\API\_1_prepare-confluence-html-for-bookstack.ps1

When prompted, provide the folder from your Confluence HTML export that contains the page .html files.

To avoid the prompt, pass the source folder:

.\API\_1_prepare-confluence-html-for-bookstack.ps1 `
  -InputPath "C:\Path\To\ConfluenceExport\SpaceFolder"

The script creates cleaned HTML files in ReadyDir from your config and embeds local attachment images.

If ReadyDir does not exist, it is created. If it already exists, its contents are deleted before the new prepared files are written.

2. Organize The Files

Arrange the prepared files before import:

API_ReadyforImport/
  Root Page.html
  Chapter Name/
    Page In Chapter.html

Import rules:

• HTML files directly inside ReadyDir become pages at the book root.
• Immediate subfolders become BookStack chapters.
• HTML files inside a subfolder become pages inside that chapter.

3. Fix Internal Links

Dry run:

.\API\_2_fix-bookstack-hyperlinks.ps1

Apply changes:

.\API\_2_fix-bookstack-hyperlinks.ps1 -Commit

This rewrites Confluence page links and local .html links to BookStack page URLs.

4. Import To BookStack

Dry run:

.\API\_3_import-ready-bookstack.ps1

Create pages and chapters:

.\API\_3_import-ready-bookstack.ps1 -Commit

Update existing pages and chapters:

.\API\_3_import-ready-bookstack.ps1 -Commit -UpdateExisting

Notes

• File names become BookStack page names.
• A trailing Confluence page ID such as _3067805697 is removed from the page name.
• --- in a file name becomes - in the page name.
• The hyperlink fixer can only fix links to files that exist under ReadyDir.
• Very large pages with many embedded images may fail with HTTP 413. Split the page or increase your BookStack/web server request size limit.
• Keep generated exports, prepared HTML, real configs, and backup scripts out of Git.

Acknowledgement

This project was built with reference to the BookStack API and the BookStack API script examples:

https://codeberg.org/bookstack/api-scripts

This project is not officially affiliated with or supported by the BookStack project.