Sync Markdown to BookStack Action

Description

This action allows to synchronize one or more Markdown files to BookStack. This makes it possible to maintain documentation within a repository while still making it available in your central documentation solution.

This action features:

• Sync to either a chapter or a book
• Use either a single file or a glob pattern to sync multiple files
• Keep your pages up to date - the action can create and update pages

Limitations

• To support globs and therefore the creation of multiple pages at once, this action uses the first headline of type # (h1) as the name for the pages
• Your Markdown files must have at least one # to be accepted by the Action
• The sync is currently one way, so deleting files from the repository won't delete the pages from BookStack
• We always push an update to BookStack which generates additional traffic, however, BookStack won't create additional revisions if the content is unchanged
• You must grab the book/chapter ID from the database or using the API to configure the action

Inputs

url

• Required
• The URL to your BookStack instance, where the files will be synced to.

token-id

• Required
• The ID of your BookStack API connection.

token-secret

• Required
• The secret of your BookStack API connection.

book-id

• Required, when chapter-id is not set
• The ID of the book to sync to.

chapter-id

• Required, when book-id is not set
• The ID of the book to sync to.

path

• The path to the Markdown file(s) to sync, you can use glob patterns for multiple files

Outputs

This action does not output anything, if everything goes well.

Example usage

uses: lazybytez/[email protected]
with:
    bookstack-url: 'https://bookstack.your.url'
    bookstack-token-id: '{{ secrets.BOOKSTACK_TOKEN_ID }}'
    bookstack-token-secret: '{{ secrets.BOOKSTACK_TOKEN_SECRET }}'
    # You only need one of book-id or chapter-id
    book-id: 123
    chapter-id: 123
    # You can either use a path to a file or a glob pattern:
    path: 'sub/directories/README.md'
    path: 'sub/*/*.md'

Development

To develop locally, you should install NodeJS 20.

The following commands can be used for local development:

# Install dependencies
$ npm install

# Format and bundle for distribution
$ npm run bundle

# Only check code style using prettier
$ npm run format:check

# Check code style and reformat
$ npm run format:write

Be sure to always run the bundler and commit the dist/ directory when doing changes to the code.

Contributing

If you want to take part in contribution, like fixing issues and contributing directly to the codebase, please visit the How to Contribute document.

Useful links

License - Contributing - Code of conduct - Issues - Pull requests

---

Copyright (c) Lazy Bytez. All rights reserved | Licensed under the MIT license.