https://github.com/lazybytez/sync-markdown-bookstack-action
Sync some markdown files from your repository with BookStack
https://github.com/lazybytez/sync-markdown-bookstack-action
actions bookstack markdown
Last synced: 3 months ago
JSON representation
Sync some markdown files from your repository with BookStack
- Host: GitHub
- URL: https://github.com/lazybytez/sync-markdown-bookstack-action
- Owner: lazybytez
- License: mit
- Created: 2023-09-21T17:48:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-24T16:55:03.000Z (over 1 year ago)
- Last Synced: 2025-01-19T21:39:20.218Z (5 months ago)
- Topics: actions, bookstack, markdown
- Language: JavaScript
- Homepage:
- Size: 343 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Sync Markdown to BookStack Action
[![gh-commit-badge][gh-commit-badge]][gh-commit]
[![gh-contributors-badge][gh-contributors-badge]][gh-contributors]
[![gh-stars-badge][gh-stars-badge]][gh-stars]
## 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
```yaml
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:
```shell
# 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][gh-contribute] document.
## Useful links
[License][gh-license] -
[Contributing][gh-contribute] -
[Code of conduct][gh-codeofconduct] -
[Issues][gh-issues] -
[Pull requests][gh-pulls]
Copyright (c) [Lazy Bytez][gh-team]. All rights reserved | Licensed under the MIT license.
[gh-commit-badge]: https://img.shields.io/github/last-commit/lazybytez/sync-markdown-bookstack-action?style=for-the-badge&colorA=302D41&colorB=cba6f7
[gh-commit]: https://github.com/lazybytez/sync-markdown-bookstack-action/commits/main
[gh-contributors-badge]: https://img.shields.io/github/contributors/lazybytez/sync-markdown-bookstack-action?style=for-the-badge&colorA=302D41&colorB=89dceb
[gh-contributors]: https://github.com/lazybytez/sync-markdown-bookstack-action/graphs/contributors
[gh-stars-badge]: https://img.shields.io/github/stars/lazybytez/sync-markdown-bookstack-action?style=for-the-badge&colorA=302D41&colorB=f9e2af
[gh-stars]: https://github.com/lazybytez/sync-markdown-bookstack-action/stargazers
[gh-contribute]: https://github.com/lazybytez/.github/blob/main/docs/CONTRIBUTING.md
[gh-license]: https://github.com/lazybytez/sync-markdown-bookstack-action/blob/main/LICENSE
[gh-codeofconduct]: https://github.com/lazybytez/.github/blob/main/docs/CODE_OF_CONDUCT.md
[gh-issues]: https://github.com/lazybytez/sync-markdown-bookstack-action/issues
[gh-pulls]: https://github.com/lazybytez/sync-markdown-bookstack-action/pulls
[gh-team]: https://github.com/lazybytez