From 1619a5960e58ac58c73c1aa5f0f927970cd4779e Mon Sep 17 00:00:00 2001 From: Sergio Mendolia Date: Sat, 30 Nov 2024 09:38:48 +0100 Subject: [PATCH] Update doc --- astro.config.mjs | 16 +++-- .../docs/account/managing-your-account.md | 3 - src/content/docs/account/themes.md | 3 - src/content/docs/concepts.mdx | 31 ---------- .../Administrator}/OpenAI-configuration.md | 0 .../guides/Administrator/adding-books.mdx | 33 ++++++++++ .../Administrator}/adding-users.md | 0 .../docs/guides/Administrator/commands.md | 52 ++++++++++++++++ .../Administrator}/edit-book.md | 0 .../docs/guides/Administrator/filesystem.md | 6 ++ .../docs/guides/Administrator/verified.md | 11 ++++ src/content/docs/guides/Developer/themes.md | 28 +++++++++ src/content/docs/guides/User/homepage.md | 3 + src/content/docs/guides/User/shelf.md | 11 ++++ src/content/docs/guides/User/sync-kobo.md | 3 + .../docs/{account => guides/User}/timeline.md | 0 .../docs/guides/User/update-settings.md | 3 + src/content/docs/index.mdx | 60 +++++++++---------- .../docs/installing/2-new-versions.mdx | 10 +++- src/content/docs/installing/dotenv-config.md | 13 ++++ src/content/docs/kobosync/docker.md | 3 - .../Adding Books/from-folder.md | 3 - .../Adding Books/upload-manually.md | 3 - .../docs/managing_books/Shelves/dynamic.md | 3 - .../docs/managing_books/Shelves/shelf.md | 3 - .../Updating Book Metadata/edit-multiple.md | 3 - .../Updating Book Metadata/verified.md | 3 - src/custom.css | 4 ++ 28 files changed, 209 insertions(+), 102 deletions(-) delete mode 100644 src/content/docs/account/managing-your-account.md delete mode 100644 src/content/docs/account/themes.md delete mode 100644 src/content/docs/concepts.mdx rename src/content/docs/{account => guides/Administrator}/OpenAI-configuration.md (100%) create mode 100644 src/content/docs/guides/Administrator/adding-books.mdx rename src/content/docs/{account => guides/Administrator}/adding-users.md (100%) create mode 100644 src/content/docs/guides/Administrator/commands.md rename src/content/docs/{managing_books/Updating Book Metadata => guides/Administrator}/edit-book.md (100%) create mode 100644 src/content/docs/guides/Administrator/filesystem.md create mode 100644 src/content/docs/guides/Administrator/verified.md create mode 100644 src/content/docs/guides/Developer/themes.md create mode 100644 src/content/docs/guides/User/homepage.md create mode 100644 src/content/docs/guides/User/shelf.md create mode 100644 src/content/docs/guides/User/sync-kobo.md rename src/content/docs/{account => guides/User}/timeline.md (100%) create mode 100644 src/content/docs/guides/User/update-settings.md delete mode 100644 src/content/docs/kobosync/docker.md delete mode 100644 src/content/docs/managing_books/Adding Books/from-folder.md delete mode 100644 src/content/docs/managing_books/Adding Books/upload-manually.md delete mode 100644 src/content/docs/managing_books/Shelves/dynamic.md delete mode 100644 src/content/docs/managing_books/Shelves/shelf.md delete mode 100644 src/content/docs/managing_books/Updating Book Metadata/edit-multiple.md delete mode 100644 src/content/docs/managing_books/Updating Book Metadata/verified.md create mode 100644 src/custom.css diff --git a/astro.config.mjs b/astro.config.mjs index ffacb98..8dbfe05 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -7,26 +7,24 @@ export default defineConfig({ base: import.meta.env.PROD?'biblioteca-doc':'', integrations: [ starlight({ - title: 'Biblioteca', + title: 'Biblioteca Docs', social: { github: 'https://github.com/biblioverse/biblioteca', }, lastUpdated: true, - + customCss: [ + // Relative path to your custom CSS file + './src/custom.css', + ], sidebar: [ { label: 'Home', link: '/' }, - { label: 'Important concepts', link: '/concepts' }, { label: 'Installation', autogenerate: { directory: 'installing' }, }, { - label: 'User accounts', - autogenerate: { directory: 'account' }, - }, - { - label: 'Managing your books', - autogenerate: { directory: 'managing_books' }, + label: 'User Guides', + autogenerate: { directory: 'guides' }, }, ], }), diff --git a/src/content/docs/account/managing-your-account.md b/src/content/docs/account/managing-your-account.md deleted file mode 100644 index 9723487..0000000 --- a/src/content/docs/account/managing-your-account.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Managing your account ---- diff --git a/src/content/docs/account/themes.md b/src/content/docs/account/themes.md deleted file mode 100644 index f8ee328..0000000 --- a/src/content/docs/account/themes.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Themes ---- diff --git a/src/content/docs/concepts.mdx b/src/content/docs/concepts.mdx deleted file mode 100644 index 1c9b75c..0000000 --- a/src/content/docs/concepts.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Concepts ---- -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -There are a few important concepts here, if this is your first read, take some time to make sure we have the same definitions -for them. -## Books -Books can be of multiple formats, but for now every book only has one format. Supported formats are epub, pdf, mobi, cbr, and cbz. - -## Shelves -Shelves are groups of books, they can be static or dynamic. - -You can manually add books to static shelves and that's it. - -You can also create dynamic shelves, which are based on a query. For example, you can create a shelf that contains all -books from your favorite authors that you haven't read and if you or an administrator adds books from these authors, -they will automatically be listed in there. - - - - - - -## File system structure and Relocation - -You can manage the file structure of your book by hand and run a command to have them in biblioteca, or you can ask biblioteca -to relocate them to a path format of your choice. - -## Metadata - diff --git a/src/content/docs/account/OpenAI-configuration.md b/src/content/docs/guides/Administrator/OpenAI-configuration.md similarity index 100% rename from src/content/docs/account/OpenAI-configuration.md rename to src/content/docs/guides/Administrator/OpenAI-configuration.md diff --git a/src/content/docs/guides/Administrator/adding-books.mdx b/src/content/docs/guides/Administrator/adding-books.mdx new file mode 100644 index 0000000..f0d15ef --- /dev/null +++ b/src/content/docs/guides/Administrator/adding-books.mdx @@ -0,0 +1,33 @@ +--- +title: Adding books +--- +import { LinkCard } from '@astrojs/starlight/components'; + +Books can be of multiple formats, but for now every book only has one format. Supported formats are +- epub +- pdf +- mobi +- cbr +- cbz + + +## Add books from command +Any book in the `public/books` folder will be added to the database when you run the `books:scan` command. If a book +already exists, its location in the filesystem will be updated, but metadata will not be overwritten. + +You can periodically run this command to automatically add new books. + +## Adding books from the interface +Adding books to the `public/books/consume` will list them in the `/books/new/consume/files` page. +This is useful when you want to add books to the library but don't want to add them to the database yet or to mount a +folder where books might arrive later (Maybe like a download folder 🫢). + + +## Verified status +When books are added to the database, their "verified" status is set to false and a link to all unverified books is +available in the menu. + + + + + \ No newline at end of file diff --git a/src/content/docs/account/adding-users.md b/src/content/docs/guides/Administrator/adding-users.md similarity index 100% rename from src/content/docs/account/adding-users.md rename to src/content/docs/guides/Administrator/adding-users.md diff --git a/src/content/docs/guides/Administrator/commands.md b/src/content/docs/guides/Administrator/commands.md new file mode 100644 index 0000000..b2284f2 --- /dev/null +++ b/src/content/docs/guides/Administrator/commands.md @@ -0,0 +1,52 @@ +--- +title: Running commands +--- + +Multiple helper commands are available to help you manage your library. +For simplicity, only the command is listed here, you will need to prefix it depending on your installation: + + +With a standard docker compose environment: `docker-compose exec php bin/console ` + +With ddev: `ddev exec bin/console ` + +## `app:create-admin-user` +Create an admin user. This commande takes the username and the password as parameters. You should need this command only +during the first installation, as you can create users from the interface. + +## `books:check` +Check the integrity of all books. + +## `books:extract-cover` +Tries to extract the cover from all books that do not have one and saves it in the `public/covers` folder. + +## `books:relocate` +Relocate all books to their calculated folder. This is necessary only if you want Biblioteca to manage your library structure. + +## `books:scan` +Will scan the `public/books` folder and add all books to the database. If a book already exists, it will be updated. + +## `books:tag` + +> First you will need to setup an openAi chatgpt key in a user's properties and run the command as this user + +Then you can run the command to generate tag for all books in the library: + +```bash +bin/console books:tag +``` + +## `cache:clear` +Clears the cache + +## `doctrine:migrations:migrate` +Executes all missing database migrations. + +## `symandy:databases:backup` +Creates a sql backup of the database in the `backups folder`. + +## `typesense:create` +Will re-create the search engine index. + +## `typesense:import` +Will re-import all books from the database to the search engine. diff --git a/src/content/docs/managing_books/Updating Book Metadata/edit-book.md b/src/content/docs/guides/Administrator/edit-book.md similarity index 100% rename from src/content/docs/managing_books/Updating Book Metadata/edit-book.md rename to src/content/docs/guides/Administrator/edit-book.md diff --git a/src/content/docs/guides/Administrator/filesystem.md b/src/content/docs/guides/Administrator/filesystem.md new file mode 100644 index 0000000..f90a564 --- /dev/null +++ b/src/content/docs/guides/Administrator/filesystem.md @@ -0,0 +1,6 @@ +--- +title: Filesystem and relocation +--- + +You can manage the file structure of your book by hand and run a command to have them in biblioteca, or you can ask biblioteca +to relocate them to a path format of your choice. \ No newline at end of file diff --git a/src/content/docs/guides/Administrator/verified.md b/src/content/docs/guides/Administrator/verified.md new file mode 100644 index 0000000..1dc7038 --- /dev/null +++ b/src/content/docs/guides/Administrator/verified.md @@ -0,0 +1,11 @@ +--- +title: Verified books +--- + +The verification status is a flag on the books. When you add a book, it will be set to false. + +If you are an administrator, there is a link in the application menu listing all boks that have not been verified yet. + +This feature allows you to know which books have been added recently and for whom you need to verify and update the metadata. + +When the flag is checked, the edition controls are removed until you uncheck it. \ No newline at end of file diff --git a/src/content/docs/guides/Developer/themes.md b/src/content/docs/guides/Developer/themes.md new file mode 100644 index 0000000..3442881 --- /dev/null +++ b/src/content/docs/guides/Developer/themes.md @@ -0,0 +1,28 @@ +--- +title: Themes +--- + +Biblioteca is configured to be easily themeable. + +By default all the template in the `templates` directory are used. + +If you create a new theme, + +1. Add your theme in the user form: + ```php + ->add('theme', ChoiceType::class, [ + 'label' => 'Theme', + 'choices' => [ + 'Default' => 'default', + 'Dark' => 'dark', + 'Cool Theme' => 'cool', + ], + ]) + ``` +2. You can overwrite all the original templates by adding a file with the same structure under your theme directory: + + In `templates/themes///` you can rewrite the template with your theme markup + + Every time a template is called, it will first check if the template exists in the theme's folder or fall back to the original one + +3. Update the CSS asset as necessary. \ No newline at end of file diff --git a/src/content/docs/guides/User/homepage.md b/src/content/docs/guides/User/homepage.md new file mode 100644 index 0000000..cb151af --- /dev/null +++ b/src/content/docs/guides/User/homepage.md @@ -0,0 +1,3 @@ +--- +title: Your homepage +--- \ No newline at end of file diff --git a/src/content/docs/guides/User/shelf.md b/src/content/docs/guides/User/shelf.md new file mode 100644 index 0000000..d313d24 --- /dev/null +++ b/src/content/docs/guides/User/shelf.md @@ -0,0 +1,11 @@ +--- +title: Simple shelves +--- + +Shelves are groups of books, they can be static or dynamic. + +You can manually add books to static shelves and that's it. + +You can also create dynamic shelves, which are based on a query. For example, you can create a shelf that contains all +books from your favorite authors that you haven't read and if you or an administrator adds books from these authors, +they will automatically be listed in there. diff --git a/src/content/docs/guides/User/sync-kobo.md b/src/content/docs/guides/User/sync-kobo.md new file mode 100644 index 0000000..e60352d --- /dev/null +++ b/src/content/docs/guides/User/sync-kobo.md @@ -0,0 +1,3 @@ +--- +title: Sync Kobo Devices +--- diff --git a/src/content/docs/account/timeline.md b/src/content/docs/guides/User/timeline.md similarity index 100% rename from src/content/docs/account/timeline.md rename to src/content/docs/guides/User/timeline.md diff --git a/src/content/docs/guides/User/update-settings.md b/src/content/docs/guides/User/update-settings.md new file mode 100644 index 0000000..5f71d3d --- /dev/null +++ b/src/content/docs/guides/User/update-settings.md @@ -0,0 +1,3 @@ +--- +title: Updating your preferences +--- diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 807655f..d58a94d 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,44 +1,38 @@ --- -title: Biblioteca -description: Get started building your docs site with Starlight. +title: Biblioteca Book Management +description: Welcome to the official Biblioteca Documentation page! Here you will find all the information you need to get started with and use Biblioteca. tableOfContents: false hero: - tagline: Managing your local library with Biblioteca - image: - file: ../../assets/houston.webp + tagline: Welcome to the official Biblioteca Documentation page! Here you will find all the information you need to get started with and use Biblioteca. actions: - - text: Concepts - link: concepts - icon: information - - text: Install + - text: Installation Guide link: installing/1-initial-setup - icon: right-arrow + icon: right-caret --- import { Card, CardGrid } from '@astrojs/starlight/components'; -## Welcome to Biblioteca -Welcome to the official Biblioteca Documentation page! Here you will find all the information you need to get started with -and use Biblioteca. + + + Biblioteca is a web application created to manage your personal library. This is an alternative to Calibre and other similar + software. + #### Why another library system? + I created Biblioteca because I wanted to have a simple and easy-to-use library manager. I was not satisfied with the existing + solutions, so I decided to make my own. + + + - Efficient and fast search + - Tagging and summarization with ChatGPT + - Easy to use interface + - Mobile friendly + - E-INK friendly + - Synchronization with Kobo Devices + - Easily Themeable + - Dynamic Shelves + - Focused on maintaing coherent metadata how you want it + - Easy to deploy with Docker + - Customizable file system structure + -## What is Biblioteca? -Biblioteca is a web application created to manage your personal library. This is an alternative to Calibre and other similar -software. - -## Why another online library? -I created Biblioteca because I wanted to have a simple and easy-to-use library manager. I was not satisfied with the existing -solutions, so I decided to make my own. - -## Features -- Efficient and fast search -- Tagging and summarization with ChatGPT -- Easy to use interface -- Mobile friendly -- E-INK friendly -- Synchronization with Kobo Devices -- Easily Themeable -- Dynamic Shelves -- Focused on maintaing coherent metadata how you want it -- Easy to deploy with Docker -- Customizable file system structure + diff --git a/src/content/docs/installing/2-new-versions.mdx b/src/content/docs/installing/2-new-versions.mdx index 87d089b..6a14a08 100644 --- a/src/content/docs/installing/2-new-versions.mdx +++ b/src/content/docs/installing/2-new-versions.mdx @@ -18,15 +18,21 @@ import { Steps } from '@astrojs/starlight/components'; ```bash docker compose exec biblioteca bin/console doctrine:migration:migrate --no-interaction ``` +3. Run the following command to rebuild the frontend assets: -3. If needed, update the typesense schema: + ```bash + docker compose exec biblioteca npm i + docker compose exec biblioteca npm run build + ``` + +4. If needed, update the typesense schema: ```bash docker-compose exec biblioteca bin/console typesense:create docker-compose exec biblioteca bin/console typesense:import ``` -4. Clear the cache: +5. Clear the cache: ```bash docker-compose exec biblioteca bin/console cache:clear diff --git a/src/content/docs/installing/dotenv-config.md b/src/content/docs/installing/dotenv-config.md index 4013795..0abb7c2 100644 --- a/src/content/docs/installing/dotenv-config.md +++ b/src/content/docs/installing/dotenv-config.md @@ -18,3 +18,16 @@ KOBO_PROXY_USE_DEV=0 KOBO_PROXY_USE_EVERYWHERE=0 KOBO_PROXY_ENABLED=1 ``` + +- `APP_ENV`: The environment the application is running in. This can be `dev` or `prod`. You should always use `prod` unless you need to debug the application. +- `APP_SECRET`: A secret key used to secure the application. Make it unique! +- `DATABASE_URL`: The URL to the database. You should not need to change this unless you are using a different database. +- `MESSENGER_TRANSPORT_DSN`: Do not change it. +- `MAILER_DSN`: Currently not used. +- `TYPESENSE_URL`: The URL to the typesense server. You should not need to change this unless you are using a different server. +- `TYPESENSE_KEY`: The key to access the typesense server. Needs to correspond to the one you set in your docker-compose file. +- `BOOK_FOLDER_NAMING_FORMAT`: The format to use to name the folders where the books are stored. You can use the following placeholders: `{authorFirst}`, `{author}`, `{title}`, `{serie}`. +- `BOOK_FILE_NAMING_FORMAT`: The format to use to name the files where the books are stored. You can use the following placeholders: `{serie}`, `{serieIndex}`, `{title}`. +- `KOBO_PROXY_USE_DEV`: If set to `1`, the kobo proxy will be used in development. +- `KOBO_PROXY_USE_EVERYWHERE`: If set to `1`, the kobo proxy will be used everywhere and all request will be forwarded to the original store. +- `KOBO_PROXY_ENABLED`: If set to `0`, the kobo proxy will be disabled. \ No newline at end of file diff --git a/src/content/docs/kobosync/docker.md b/src/content/docs/kobosync/docker.md deleted file mode 100644 index abdb9da..0000000 --- a/src/content/docs/kobosync/docker.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Docker ---- diff --git a/src/content/docs/managing_books/Adding Books/from-folder.md b/src/content/docs/managing_books/Adding Books/from-folder.md deleted file mode 100644 index 5c70209..0000000 --- a/src/content/docs/managing_books/Adding Books/from-folder.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: From a folder ---- diff --git a/src/content/docs/managing_books/Adding Books/upload-manually.md b/src/content/docs/managing_books/Adding Books/upload-manually.md deleted file mode 100644 index e09f3a9..0000000 --- a/src/content/docs/managing_books/Adding Books/upload-manually.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Manually Upload new books ---- diff --git a/src/content/docs/managing_books/Shelves/dynamic.md b/src/content/docs/managing_books/Shelves/dynamic.md deleted file mode 100644 index 24457df..0000000 --- a/src/content/docs/managing_books/Shelves/dynamic.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Dynamic Shelves ---- diff --git a/src/content/docs/managing_books/Shelves/shelf.md b/src/content/docs/managing_books/Shelves/shelf.md deleted file mode 100644 index 2b9887a..0000000 --- a/src/content/docs/managing_books/Shelves/shelf.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Simple shelves ---- diff --git a/src/content/docs/managing_books/Updating Book Metadata/edit-multiple.md b/src/content/docs/managing_books/Updating Book Metadata/edit-multiple.md deleted file mode 100644 index 8f7a5e5..0000000 --- a/src/content/docs/managing_books/Updating Book Metadata/edit-multiple.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Edit multiple books ---- diff --git a/src/content/docs/managing_books/Updating Book Metadata/verified.md b/src/content/docs/managing_books/Updating Book Metadata/verified.md deleted file mode 100644 index e5bf496..0000000 --- a/src/content/docs/managing_books/Updating Book Metadata/verified.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Verified books ---- diff --git a/src/custom.css b/src/custom.css new file mode 100644 index 0000000..f12f142 --- /dev/null +++ b/src/custom.css @@ -0,0 +1,4 @@ +:root { + --sl-content-width: 90%; + --sl-text-5xl: 3.5rem; +} \ No newline at end of file