BookStack Code Mirror - api-scripts/blob - ruby-generate-csv-list-of-all-pages/README.md

1 # BookStack Data Exporter

3 This Ruby script allows you to export data from a BookStack instance into a CSV file. The exported data includes information about pages, books, and shelves, along with their respective URLs and modification dates.

4

5 ## Prerequisites

6

7 Before running the script, make sure you have the following:

8

9 - Ruby installed on your system

10 - Access to a BookStack instance with API enabled

11 - BookStack API token ID and token secret

12

13 ## Installation

14

15 1. Clone this repository or download the script file.

16 2. Install the required dependencies by running the following command:

17

18 ```

19 bundle install

20 ```

21

22 3. Create a `.env` file in the same directory as the script and provide the following environment variables:

23

24 ```

25 BS_URL=<your_bookstack_url>

26 BS_TOKEN_ID=<your_api_token_id>

27 BS_TOKEN_SECRET=<your_api_token_secret>

28 ```

29

30 Replace `<your_bookstack_url>`, `<your_api_token_id>`, and `<your_api_token_secret>` with your actual BookStack URL, API token ID, and API token secret, respectively.

31

32 ## Usage

33

34 To run the script and export the data, execute the following command:

35

36 ```

37 ruby export_bookstack_data.rb

38 ```

39

40 The script will retrieve data from your BookStack instance and generate a CSV file named `bookstack_data.csv` in the same directory.

41

42 ## CSV Output

43

44 The generated CSV file will have the following columns:

45

46 - Type: Indicates whether the row represents a page or a book.

47 - ID: The unique identifier of the page or book.

48 - Name: The name of the page or book.

49 - URL: The URL of the page or book, formatted as an Excel hyperlink.

50 - Book ID: The ID of the book to which the page belongs (applicable only for pages).

51 - Book Name: The name of the book to which the page belongs (applicable only for pages).

52 - Book URL: The URL of the book, formatted as an Excel hyperlink (applicable only for pages).

53 - Shelf Name: The name of the shelf to which the book belongs.

54 - Date Modified: The last modification date of the page or book.

55

56 The URLs in the 'URL' and 'Book URL' columns are wrapped in the `=HYPERLINK()` function, allowing you to easily access the respective pages and books directly from the CSV file when opened in Excel.

57 HYPERLINK() - is an Excel shortcut to make URL clickable, feel free to remove, if you don't use Excel.

58

59 ## Logging

60

61 Logging to STDOUT, but can be adjusted to a file.

62

63 ## Example

64

65 Here's an example of how the generated CSV file might look.

66

67 ```

68 Type,ID,Name,URL,Book ID,Book Name,Book URL,Shelf Name,Date Modified

69 Page,1,Introduction,=HYPERLINK("https://example.com/books/1/page/1"),1,User Guide,=HYPERLINK("https://example.com/books/1"),Getting Started,2023-05-01T10:00:00.000000Z

70 Page,2,Installation,=HYPERLINK("https://example.com/books/1/page/2"),1,User Guide,=HYPERLINK("https://example.com/books/1"),Getting Started,2023-05-02T11:30:00.000000Z

71 Book,1,User Guide,=HYPERLINK("https://example.com/books/1"),,,,Getting Started,2023-05-01T09:00:00.000000Z

72 ```

73

74 ## License

75

76 This script is released under the [MIT License](LICENSE).

77

78 Feel free to customize and adapt the script to suit your specific requirements.