The below outlines the structure of the format:
- **ZIP archive container**
- - **data.json** - Application data.
+ - **data.json** - Export data.
- **files/** - Directory containing referenced files.
- - *...file.ext*
+ - *file-a*
+ - *file-b*
+ - *...*
## References
-TODO - Define how we reference across content:
-TODO - References to files from data.json
-TODO - References from in-content to file URLs
-TODO - References from in-content to in-export content (page cross links within same export).
+Some properties in the export data JSON are indicated as `String reference`, and these are direct references to a file name within the `files/` directory of the ZIP. For example, the below book cover is directly referencing a `files/4a5m4a.jpg` within the ZIP which would be expected to exist.
-## Application Data - `data.json`
+```json
+{
+ "book": {
+ "cover": "4a5m4a.jpg"
+ }
+}
+```
+
+Within HTML and markdown content, you may require references across to other items within the export content.
+This can be done using the following format:
+
+```
+[[bsexport:<object>:<reference>]]
+```
+
+References are to the `id` for data objects.
+Here's an example of each type of such reference that could be used:
+
+```
+[[bsexport:image:22]]
+[[bsexport:attachment:55]]
+[[bsexport:page:40]]
+[[bsexport:chapter:2]]
+[[bsexport:book:8]]
+```
+
+## Export Data - `data.json`
The `data.json` file is a JSON format file which contains all structured data for the export. The properties are as follows:
#### Book
-TODO
+- `id` - Number, optional, original ID for the book from exported system.
+- `name` - String, required, name/title of the book.
+- `description_html` - String, optional, HTML description content.
+- `cover` - String reference, options, reference to book cover image.
+- `chapters` - [Chapter](#chapter) array, optional, chapters within this book.
+- `pages` - [Page](#page) array, optional, direct child pages for this book.
+- `tags` - [Tag](#tag) array, optional, tags assigned to this book.
+
+The `pages` are not all pages within the book, just those that are direct children (not in a chapter). To build an ordered mixed chapter/page list for the book, as what you'd see in BookStack, you'd need to combine `chapters` and `pages` together and sort by their `priority` value (low to high).
#### Chapter
-TODO
+- `id` - Number, optional, original ID for the chapter from exported system.
+- `name` - String, required, name/title of the chapter.
+- `description_html` - String, optional, HTML description content.
+- `priority` - Number, optional, integer order for when shown within a book (shown low to high).
+- `pages` - [Page](#page) array, optional, pages within this chapter.
+- `tags` - [Tag](#tag) array, optional, tags assigned to this chapter.
#### Page
-TODO
+- `id` - Number, optional, original ID for the page from exported system.
+- `name` - String, required, name/title of the page.
+- `html` - String, optional, page HTML content.
+- `markdown` - String, optional, user markdown content for this page.
+- `priority` - Number, optional, integer order for when shown within a book (shown low to high).
+- `attachments` - [Attachment](#attachment) array, optional, attachments uploaded to this page.
+- `images` - [Image](#image) array, optional, images used in this page.
+- `tags` - [Tag](#tag) array, optional, tags assigned to this page.
+
+To define the page content, either `markdown` or `html` should be provided. Ideally these should be limited to the range of markdown and HTML which BookStack supports.
+
+The page editor type, and edit content will be determined by what content is provided. If non-empty `markdown` is provided, the page will be assumed as a markdown editor page (where permissions allow) and the HTML will be rendered from the markdown content. Otherwise, the provided `html` will be used as editor and display content.
#### Image
-TODO
+- `id` - Number, optional, original ID for the page from exported system.
+- `name` - String, required, name of image.
+- `file` - String reference, required, reference to image file.
+- `type` - String, required, must be 'gallery' or 'drawio'
+
+File must be an image type accepted by BookStack (png, jpg, gif, webp).
+Images of type 'drawio' are expected to be png with draw.io drawing data
+embedded within it.
#### Attachment
-TODO
+- `id` - Number, optional, original ID for the attachment from exported system.
+- `name` - String, required, name of attachment.
+- `link` - String, semi-optional, URL of attachment.
+- `file` - String reference, semi-optional, reference to attachment file.
+- `order` - Number, optional, integer order of the attachments (shown low to high).
+
+Either `link` or `file` must be present, as that will determine the type of attachment.
#### Tag
-TODO
\ No newline at end of file
+- `name` - String, required, name of the tag.
+- `value` - String, optional, value of the tag (can be empty).
+- `order` - Number, optional, integer order of the tags (shown low to high).
\ No newline at end of file
projects / bookstack / blobdiff