mirror/AudioBookRequest
1
0
Fork 0
mirror of https://github.com/markbeep/AudioBookRequest.git synced 2025-12-30 10:09:34 -06:00
Code Issues Packages Projects Releases Wiki Activity

add docs page

Browse Source
This commit is contained in:
Markbeep
2025-06-09 17:17:31 +02:00
parent 10823414ff
commit a9de9d5990
38 changed files with 1490 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.github/workflows/docs.yaml vendored Normal file
View File

@@ -0,0 +1,37 @@
name: Generate Docs
on:
push:
paths:
- docs/**
- .github/workflows/docs.yaml
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: "0.147.7"
extended: true
- name: Setup Node
uses: actions/setup-node@v2
with:
node-version: "16.x"
- run: |
cd docs
npm i
npm run build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/public
publish_branch: docs

61
README.md
View File

@@ -22,13 +22,13 @@ If you've heard of Overseer, Ombi, or Jellyseer; this is in the similar vein, <i
- [ABR](#abr)
- [OpenID Connect](#openid-connect)
- [Getting locked out](#getting-locked-out)
- [Alternative Deployments](#alternative-deployments)
- [Environment Variables](#environment-variables)
- [Contributing](#contributing)
- [Local Development](#local-development)
- [Initialize Database](#initialize-database)
- [Running](#running)
- [Docker Compose](#docker-compose)
- [Docs](#docs)
# Getting Started
@@ -105,61 +105,6 @@ Applying settings does not directly invalidate your current session. To test OID
In the case of an OIDC misconfiguration, i.e. changing a setting like your client secret on your auth server, can cause you to be locked out. In these cases, you can head to `/login?backup=1`, where you can log in using your root admin credentials allowing you to correctly configure any settings.
## Alternative Deployments
Docker image is located on [dockerhub](https://hub.docker.com/r/markbeep/audiobookrequest).
**NOTE:** It is not recommended to use `:latest` in case of incompatible changes that are not backwards compatible. For versioning, [SemVer](https://semver.org/) is used.
For experimental builds (latest commits to `main`), the `:nightly` version can be used.
**Docker compose**
```yaml
services:
web:
image: markbeep/audiobookrequest:1
ports:
- "8000:8000"
volumes:
- ./config:/config
```
**Kubernetes**
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: audiobookrequest
labels:
app: audiobookrequest
spec:
replicas: 1
selector:
matchLabels:
app: audiobookrequest
template:
metadata:
labels:
app: audiobookrequest
spec:
containers:
- name: audiobookrequest
image: markbeep/audiobookrequest:1
imagePullPolicy: Always
volumeMounts:
- mountPath: /config
name: abr-config
ports:
- name: http-request
containerPort: 8000
volumes:
- name: abr-config
hostPath:
path: /mnt/disk/AudioBookRequest/
```
### Environment Variables
| ENV | Description | Default |
@@ -237,3 +182,7 @@ The docker compose can also be used to run the app locally:
```bash
docker compose up --build
```
# Docs
[Hugo](https://gohugo.io) is used to generate the docs page. It can be found in the `/docs` directory.

5
docs/.gitignore vendored Normal file
View File

@@ -0,0 +1,5 @@
/public
resources/
node_modules/
package-lock.json
.hugo_build.lock

4
docs/Dockerfile Normal file
View File

@@ -0,0 +1,4 @@
FROM floryn90/hugo:ext-alpine
RUN apk add git && \
git config --global --add safe.directory /src

201
docs/LICENSE Normal file
View File

@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

190
docs/README.md Normal file
View File

@@ -0,0 +1,190 @@
# Docsy Theme
[Docsy][] is a [Hugo theme module][] for technical documentation sites,
providing easy site navigation, structure, and more. This Project uses the Docsy
theme component as a hugo module.
In this project, the Docsy theme is pulled in as a Hugo module, together with
its dependencies:
```console
$ hugo mod graph
...
```
For Docsy documentation, see [Docsy user guide][].
## Working on the docs
Depending on your environment you may need to adjust the top-level `module`
settings in your project's Hugo config file, for example, by adding a proxy to
use when downloading remote modules. You can find details of what these
configuration settings do in the
[Hugo modules documentation](https://gohugo.io/hugo-modules/configuration/#module-config-top-level).
Once your settings are adjusted, you can edit your own versions of the site’s
source files.
If you want to do SCSS edits and want to publish these, you need to install
`PostCSS`
```bash
npm install
```
## Running the website locally
Building and running the site locally requires a recent `extended` version of
[Hugo](https://gohugo.io). You can find out more about how to install Hugo for
your environment in our
[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation)
guide.
Once you've made your working copy of the site repo, from the repo root folder,
run:
```bash
hugo server
```
## Running a container locally
You can run docsy-example inside a [Docker](https://docs.docker.com/) container,
the container runs with a volume bound to the `docsy-example` folder. This
approach doesn't require you to install any dependencies other than
[Docker Desktop](https://www.docker.com/products/docker-desktop) on Windows and
Mac, and [Docker Compose](https://docs.docker.com/compose/install/) on Linux.
1. Build the docker image
```bash
docker-compose build
```
1. Run the built image
```bash
docker-compose up
```
> NOTE: You can run both commands at once with `docker-compose up --build`.
1. Verify that the service is working.
Open your web browser and type `http://localhost:1313` in your navigation
bar, This opens a local instance of the docsy-example homepage. You can now
make changes to the docsy example and those changes will immediately show up
in your browser after you save.
### Cleanup
To stop Docker Compose, on your terminal window, press **Ctrl + C**.
To remove the produced images run:
```bash
docker-compose rm
```
For more information see the [Docker Compose documentation][].
## Using a local Docsy clone
Make sure your installed go version is `1.18` or higher.
Clone the latest version of the docsy theme into the parent folder of your
project. The newly created repo should now reside in a sibling folder of your
site's root folder.
```shell
cd root-of-your-site
git clone --branch v0.12.0 https://github.com/google/docsy.git ../docsy
```
Now run:
```shell
HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**"
```
or, when using npm, prepend `local` to the script you want to invoke, e.g.:
```shell
npm run local serve
```
By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix
`local` when using npm), the server now watches all files and directories inside
the sibling directory `../docsy` , too. Any changes inside the local `docsy`
theme clone are now immediately picked up (hot reload), you can instantly see
the effect of your local edits.
In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE`
to tell hugo about the local workspace file `docsy.work`. Alternatively, you can
declare the workspace file inside your settings file `hugo.toml`:
```toml
[module]
workspace = "docsy.work"
```
Your project's `hugo.toml` file already contains these lines, the directive for
workspace assignment is commented out, however. Remove the two trailing comment
characters '//' so that this line takes effect.
## Troubleshooting
As you run the website locally, you may run into the following error:
```console
$ hugo server
WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information.
Start building sites …
hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio
Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
Built in 27 ms
```
This error occurs if you are running an outdated version of Hugo. As of docsy
theme version `v0.12.0`, hugo version `0.146.0` or higher is required. See this
[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo)
of the user guide for instructions on how to install Hugo.
Or you may be confronted with the following error:
```console
$ hugo server
INFO 2021/01/21 21:07:55 Using config file:
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
Built in 288 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
```
This error occurs if you have not installed the extended version of Hugo. See
this
[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo)
of the user guide for instructions on how to install Hugo.
Or you may encounter the following error:
```console
$ hugo server
Error: failed to download modules: binary with name "go" not found
```
This error occurs if the `go` programming language is not available on your
system. See this
[section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language)
of the user guide for instructions on how to install `go`.
[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
[deploys]: https://app.netlify.com/sites/docsy-example/deploys
[Docsy user guide]: https://docsy.dev/docs
[Docsy]: https://github.com/google/docsy
[example.docsy.dev]: https://example.docsy.dev
[Hugo theme module]:
https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
[Netlify]: https://netlify.com
[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/

6
docs/assets/scss/_variables_project.scss Normal file
View File

@@ -0,0 +1,6 @@
/*
Add styles or override variables from the theme here.
*/

15
docs/config.yaml Normal file
View File

@@ -0,0 +1,15 @@
# THIS IS A TEST CONFIG ONLY!
# FOR THE CONFIGURATION OF YOUR SITE USE hugo.yaml.
#
# As of Docsy 0.7.0, Hugo 0.110.0 or later must be used.
#
# The sole purpose of this config file is to detect Hugo-module builds that use
# an older version of Hugo.
#
# DO NOT add any config parameters to this file. You can safely delete this file
# if your project is using the required Hugo version.
module:
hugoVersion:
extended: true
min: 0.110.0

19
docs/content/_index.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: AudioBookRequest
---
{{< blocks/cover title="Welcome to AudioBookRequest!" image_anchor="top" height="full" >}}
<a class="btn btn-lg btn-primary me-3 mb-4" href="/docs/getting-started"> Get
started <i class="fas fa-arrow-alt-circle-right ms-2"></i> </a>
<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/markbeep/AudioBookRequest">
View Code <i class="fab fa-github ms-2 "></i> </a>
<p class="lead mt-5">Audiobook request management/wishlist for Plex/Audiobookshelf/Jellyfin </p>
{{< blocks/link-down color="info" >}}
{{< /blocks/cover >}}
{{% blocks/lead color="primary" %}} Your tool for handling audiobook requests on
a Plex/Audiobookshelf/Jellyfin instance.
If you've heard of Overseer, Ombi, or Jellyseer; this is in the similar vein,
<ins>but for audiobooks</ins>. {{% /blocks/lead %}}

5
docs/content/community/_index.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: Community
menu: {main: {weight: 40}}
# Add blocks of content here to add more sections to the community page
---

41
docs/content/docs/_index.md Normal file
View File

@@ -0,0 +1,41 @@
---
title: Overview
description: Welcome to the documentation for AudioBookRequest.
linkTitle: Overview
menu: { main: { weight: 20 } }
---
## What is it?
AudioBookRequest is a tool that can be used in combination with media servers
like plex/audiobookserver/jellyfin/etc. to easily set up a pipeline for creating
a wishlist of audiobooks you want to listen to.
## Why do I want it?
Help your user know if your project will help them. Useful information can
include:
- **What is it good for?**: If you have multiple people using your ABS instance
and you don't want them to always have to message you for new books or you
don't want to give them access to something like Readarr/Prowlarr, you can use
AudioBookRequest to allow them to easily request any books they want to listen
to and have it notify and/or automatically start any required downloads.
- **What is it not good for?**: AudioBookRequest is **not** a full replacement
for Readarr, nor is that the plan. Readarr does a lot of things, but it is
also currently in a very messy state development-wise. ABR does not currently
keep track of your library, while automatically downloading new releases and
trying to upgrade the quality of already existing audiobooks. These are
features that are less relevant with audiobooks.
- **What is it _not yet_ good for?**: AudioBookRequest is currently unable to
move any downloads, add metadata to files, or rename files according to some
structure.
## Where should I go next?
Head on over to the following sections to learn more about AudioBookRequest:
- [Getting Started](/docs/getting-started/): Get started with AudioBookRequest
- [Notifications](/docs/notifications/): Check out some example code!

6
docs/content/docs/concepts/_index.md Normal file
View File

@@ -0,0 +1,6 @@
---
title: Concepts
description: >
Concepts used in ABR in more detail.
weight: 4
---

20
docs/content/docs/concepts/environment-variables.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: 'Environment Variables'
description: >
List of the environment variables that can be set.
date: 2025-06-09T13:46:33+02:00
---
| ENV | Description | Default |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `ABR_APP__PORT` | The port to run the server on. | 8000 |
| `ABR_APP__DEBUG` | If to enable debug mode. Not recommended for production. | false |
| `ABR_APP__OPENAPI_ENABLED` | If set to `true`, enables an OpenAPI specs page on `/docs`. | false |
| `ABR_APP__CONFIG_DIR` | The directory path where persistant data and configuration is stored. If ran using Docker or Kubernetes, this is the location a volume should be mounted to. | /config |
| `ABR_APP__LOG_LEVEL` | One of `DEBUG`, `INFO`, `WARN`, `ERROR`. | INFO |
| `ABR_APP__BASE_URL` | Defines the base url the website is hosted at. If the website is accessed at `example.org/abr/`, set the base URL to `/abr/` | |
| `ABR_DB__SQLITE_PATH` | If relative, path and name of the sqlite database in relation to `ABR_APP__CONFIG_DIR`. If absolute (path starts with `/`), the config dir is ignored and only the absolute path is used. | db.sqlite |
{{< alert title="Note" >}} There are two underscores (`__`) between the first
and second part of each environment variable like between `ABR_APP` and `PORT`.
{{< /alert >}}

88
docs/content/docs/contribution-guidelines.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: Contribution Guidelines
description: How to contribute to the docs.
weight: 10
---
We use [Hugo](https://gohugo.io/) to format and generate our website, the
[Docsy](https://github.com/google/docsy) theme for styling and site structure,
and [Github Pages](https://pages.github.com/) to manage the deployment of the
site. Hugo is an open-source static site generator that provides us with
templates, content organisation in a standard directory structure, and a website
generation engine. You write the pages in Markdown (or HTML if you want), and
Hugo wraps them up into a website.
All submissions require review. We use GitHub pullas requests for this purpose.
Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for
more information on using pull requests.
## Quick start with Hugo
Here's a quick guide to updating the docs. It assumes you're familiar with the
GitHub workflow and you're happy to use the automated preview of your doc
updates:
1. Fork the
[AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest) on
GitHub.
1. Make your changes and send a pull request (PR).
1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
it's a work in progress. (**Don't** add the Hugo property "draft = true" to
the page front matter, because that prevents the auto-deployment of the
content preview described in the next point.)
1. When you're ready for a review, add a comment to the PR, and remove any "WIP"
markers.
## Updating a single page
If you've just spotted something you'd like to change while using the docs,
Docsy has a shortcut for you:
1. Click **Edit this page** in the top right hand corner of the page.
1. If you don't already have an up to date fork of the project repo, you are
prompted to get one - click **Fork this repository and propose changes** or
**Update your Fork** to get an up to date version of the project to edit. The
appropriate page in your fork is displayed in edit mode.
1. Follow the rest of the [Quick start with Hugo](#quick-start-with-hugo)
process above to make, preview, and propose your changes.
## Previewing your changes locally
If you want to run your own local Hugo server to preview your changes as you
work:
1. Follow the instructions in [Getting started](/docs/getting-started/docs) to
install Hugo and any other tools you need. You'll need at least **Hugo
version 0.146.0** (we recommend using the most recent available version), and
it must be the **extended** version, which supports SCSS.
2. Fork the
[AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest) into
your own project, then create a local copy using `git clone`.
```
git clone --branch v0.12.0 --depth 1 https://github.com/markbeep/AudioBookRequest.git
```
3. Run `hugo server` in the site root directory. By default your site will be
available at http://localhost:1313/. Now that you're serving your site
locally, Hugo will watch for changes to the content and automatically refresh
your site.
4. Continue with the usual GitHub workflow to edit files, commit them, push the
changes up to your fork, and create a pull request.
## Creating an issue
If you've found a problem in the docs, but you're not sure how to fix it
yourself, please create an issue in the
[AudioBookRequest repo](https://github.com/markbeep/AudioBookRequest/issues).
You can also create an issue about a specific page by clicking the **Create
Issue** button in the top right hand corner of the page.
## Useful resources
- [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including
how it manages navigation, look and feel, and multi-language support.
- [Hugo documentation](https://gohugo.io/documentation/): Comprehensive
reference for Hugo.
- [Github Hello World!](https://guides.github.com/activities/hello-world/): A
basic introduction to GitHub concepts and workflow.

19
docs/content/docs/getting-started/_index.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: Getting Started
description: What does your user need to know to try your project?
categories: []
tags: [setup]
weight: 1
---
## Prerequisites
AudioBookRequest has been packaged as a [Docker](https://www.docker.com/) image
to make it easy to deploy and run on servers. While it is possible to run ABR
without Docker, that option should be avoided if possible and only used for
local development, as a lot of things can change from version to version.
## Setup
Head to [Running the app](/docs/getting-started/running-the-app) for
instructions on how to run ABR.

6
docs/content/docs/getting-started/docs.md Normal file
View File

@@ -0,0 +1,6 @@
---
title: "Docs"
date: 2025-06-09T13:52:47+02:00
draft: true
---

14
docs/content/docs/getting-started/running-the-app/_index.md Normal file
View File

@@ -0,0 +1,14 @@
---
title: Running the app
description: Getting AudioBookRequest up and running.
categories: [Setup]
tags: []
weight: 1
---
The app has a docker image that simplifies the deployment. The preferred methods
of running the application all revolve around running the Docker image in
different ways.
Select the method you want to use to deploy below or if your tool is not listed
(for example Portainer), head to the [docker](./docker.md) page.

40
docs/content/docs/getting-started/running-the-app/bare-metal.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: 'Bare Metal'
date: 2025-06-09T13:03:35+02:00
description: >
How to get started **without** Docker.
categories: [Setup]
tags: [development]
weight: 10
---
{{< alert color="warning" title="Warning" >}} The bare metal approach should
only be the last option. Try to get it working with Docker or get support on the
Discord server before trying to set ABR up for a bare metal deployment.
There are no guarantees that if one version works locally that it won't suddenly
break in the next because of a new dependency, new file structure or something
else. {{< /alert >}}
To run ABR locally without Docker, the same steps as for the
[local development](/docs/local-development) have to be followed. First, follow
the instructions to get local development working.
Once local development works, there are a few adjustments that have to be made
to run the app in production mode instead of debug/local mode.
1. Delete the `.env.local` file or delete all contents in it.
2. Run the python script to fetch and download all required javascript files:
`uv run python /app/util/fetch_js.py`. This should populate your `static/`
directory with some new js files.
3. Instead of running `fastapi dev` you want to execute `fastapi start` to start
the webserver.
4. Create a file called `.env` and place any environment variables you want to
set in there.
5. If you intend to change the port (documented as the env variable
`ABR_APP__PORT`), you'll have to run fastapi with the `--port <PORT>` flag:
```bash
fastapi run --port 5432
```
With these changes your deployment will be running in production mode.

40
docs/content/docs/getting-started/running-the-app/docker-compose.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: 'Docker Compose'
date: 2025-06-09T13:03:35+02:00
description: >
How to get started using Docker-Compose.
categories: [Setup]
tags: [docker]
weight: 2
---
Docker-compose works the similar way as [Docker](./docker.md).
The basic docker compose file is as follows:
```yaml
services:
web:
image: markbeep/audiobookrequest:1
ports:
- '8000:8000'
volumes:
- ./config:/config
```
If you want to add any environment variables, you can add them as explained
[here](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/).
It would look along the lines of this:
```yaml
services:
web:
image: markbeep/audiobookrequest:1
ports:
- '8000:5432'
volumes:
- ./config:/config
environment:
ABR_APP__PORT: 5432
ABR_APP__OPENAPI_ENABLED: true
```

33
docs/content/docs/getting-started/running-the-app/docker.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: 'Docker'
date: 2025-06-09T13:03:35+02:00
description: >
How to get started using Docker.
categories: [Setup]
tags: [docker]
weight: 1
---
If you prefer to run the app manually with docker, you can simply run the
following command:
```bash
docker run -p 8000:8000 -v $(pwd)/config:/config markbeep/audiobookrequest:1
```
This will start the container on port 8000 and create the `config/` directory in
your current working directory.
The above command might break on Windows. Instead, use
`${PWD}\config:/config ...` in PowerShell or `%cd%\config:/config ...` in
Windows Command Prompt.
{{% alert title="Versions" %}}The `:1` at the end denotes the image version.
Check [dockerhub](https://hub.docker.com/r/markbeep/audiobookrequest/tags) for
any other versions you can use instead.
The `:latest` tag will give you the last non-nightly release, but it is not
recommended incase of changes that are not backwards compatible.
For experimental builds (latest commits in the `main` branch of the repository),
the `:nightly` version tag can be used. {{% /alert %}}

46
docs/content/docs/getting-started/running-the-app/kubernetes.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: 'Kubernetes'
date: 2025-06-09T13:03:35+02:00
description: >
How to get started using Kubernetes.
categories: [Setup]
tags: [docker]
weight: 3
---
Here's an example for a kubernetes deployment file you'd use:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: audiobookrequest
labels:
app: audiobookrequest
spec:
replicas: 1
selector:
matchLabels:
app: audiobookrequest
template:
metadata:
labels:
app: audiobookrequest
spec:
containers:
- name: audiobookrequest
image: markbeep/audiobookrequest:1
imagePullPolicy: Always
volumeMounts:
- mountPath: /config
name: abr-config
ports:
- name: http-request
containerPort: 8000
volumes:
- name: abr-config
hostPath:
path: /mnt/disk/AudioBookRequest/
```
For the volume you can assign it a host path on a node, or assign it to a PVC.

98
docs/content/docs/local-development/_index.md Normal file
View File

@@ -0,0 +1,98 @@
---
title: Local Development
description: How to set up the project for local development.
categories: [Development]
tags: [local]
weight: 9
---
## Requirements
- Python >3.12
- [uv](https://docs.astral.sh/uv/). Used as the package manager
- node.js. Exact version is not too important. Too old versions might fail when
installing packages.
## Setup
Virtual environments help isolate any installed packages to this directory.
Project was made with `Python 3.12` and uses new generics introduced in 3.12.
Older python versions might not work or could have incorrect typing.
For improved dependency management, `uv` is used instead of `pip`.
```sh
# This creates the venv as well as installs all dependencies
uv sync
```
For local development, environment variables can be added to `.env.local` and
they'll be used wherever required. This file is not used in production.
## Initialize Database
[Alembic](https://alembic.sqlalchemy.org/en/latest/) is used to create database
migrations. Run the following before starting up the application for the first
time. It will initialize the directory if non-existant, create the database file
as well as execute any required migrations.
```sh
uv run alembic upgrade heads
```
_In case of any model changes, remember to create migrations using
`alembic revision --autogenerate -m "<message>"`._
## Generate the CSS files
[Tailwindcss](https://tailwindcss.com/) is used to style elements using CSS. On
top of that, [daisyUI](https://daisyui.com/) is for easy and consistent
component styling.
Install daisyUI and start Tailwindcss watcher. Required for any CSS styling.
```sh
npm i
uv run tailwindcss -i static/tw.css -o static/globals.css --watch
# Alternatively npx can be used to run tailwindcss
npx @tailwindcss/cli@4 -i static/tw.css -o static/globals.css --watch
```
Tailwind has to run anytime something is changed in the HTML template files.
## Run the app
Running the application is best done in multiple terminals:
1. Start FastAPI dev mode:
```sh
uv run fastapi dev
```
Website can be visited at http://localhost:8000.
2. _Optional:_ Start browser-sync. This hot reloads the website when the html
template or python files are modified:
```sh
browser-sync http://localhost:8000 --files templates/** --files app/**
```
**NOTE**: Website has to be visited at http://localhost:3000 instead.
## Docker Compose
The docker compose can also be used to run the app locally. Any services that
are required can be added to it for easy testing:
```bash
docker compose up --build
```
The local context (ABR) is in a docker compose profile called `local`, which is
only run if explicitly stated as follows:
```bash
docker compose --profile local up
```

7
docs/content/docs/tutorials/_index.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: 'Tutorials'
date: 2025-06-09T13:47:04+02:00
description: >
Tutorials about how to setup certain features with more detail.
weight: 4
---

8
docs/content/docs/tutorials/notifications/_index.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: 'Notifications'
date: 2025-06-09T13:47:04+02:00
description: >
How to send notifications.
---
{{< alert title="Todo" >}}{{< /alert >}}

8
docs/content/docs/tutorials/notifications/discord.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: 'Discord'
description: >
Sending notifications to Discord.
date: 2025-06-09T13:46:58+02:00
---
{{< alert title="Todo" >}}{{< /alert >}}

4
docs/content/search.md Normal file
View File

@@ -0,0 +1,4 @@
---
title: Search Results
layout: search
---

10
docs/docker-compose.yaml Normal file
View File

@@ -0,0 +1,10 @@
services:
site:
# image: docsy/docsy-example
build:
context: .
command: server
ports:
- '1313:1313'
volumes:
- .:/src

5
docs/docsy.work Normal file
View File

@@ -0,0 +1,5 @@
go 1.19
use .
use ../docsy/ // Local docsy clone resides in sibling folder to this project
// use ./themes/docsy/ // Local docsy clone resides in themes folder

0
docs/docsy.work.sum Normal file
View File

5
docs/go.mod Normal file
View File

@@ -0,0 +1,5 @@
module github.com/markbeep/AudioBookRequest
go 1.12
require github.com/google/docsy v0.12.0

6
docs/go.sum Normal file
View File

@@ -0,0 +1,6 @@
github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3 h1:/iluJkJiyTAdnqrw3Yi9rH2HNHhrrtCmj8VJe7I6o3w=
github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
github.com/google/docsy v0.12.0 h1:CddZKL39YyJzawr8GTVaakvcUTCJRAAYdz7W0qfZ2P4=
github.com/google/docsy v0.12.0/go.mod h1:1bioDqA493neyFesaTvQ9reV0V2vYy+xUAnlnz7+miM=
github.com/twbs/bootstrap v5.3.6+incompatible h1:efmXVyq839m5QQ0+JBUdQQ1TrmoBqvQ5kRhUueKsH+4=
github.com/twbs/bootstrap v5.3.6+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=

220
docs/hugo-disabled.toml Normal file
View File

@@ -0,0 +1,220 @@
baseURL = "https://example.docsy.dev/"
title = "Goldydocs"
# Language settings
contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
# Useful when translating.
enableMissingTranslationPlaceholders = true
enableRobotsTXT = true
# Will give values to .Lastmod etc.
enableGitInfo = true
# Comment out to disable taxonomies in Docsy
# disableKinds = ["taxonomy"]
# You can add your own taxonomies
[taxonomies]
tag = "tags"
category = "categories"
[params.taxonomy]
# set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloud = ["tags", "categories"]
# If used, must have same length as taxonomyCloud
taxonomyCloudTitle = ["Tag Cloud", "Categories"]
# set taxonomyPageHeader = [] to hide taxonomies on the page headers
taxonomyPageHeader = ["tags", "categories"]
# Highlighting config
pygmentsCodeFences = true
pygmentsUseClasses = false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic = false
#pygmentsOptions = "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle = "tango"
# Configure how URLs look like per section.
[permalinks]
blog = "/:section/:year/:month/:day/:slug/"
# Image processing configuration.
[imaging]
resampleFilter = "CatmullRom"
quality = 75
anchor = "smart"
# Language configuration
[languages]
[languages.en]
languageName ="English"
title = "Goldydocs"
[languages.en.params]
description = "A Docsy example site"
[languages.no]
languageName ="Norsk"
contentDir = "content/no"
title = "Gulldoks"
[languages.no.params]
description = "Docsy er operativsystem for skyen"
time_format_default = "02.01.2006"
time_format_blog = "02.01.2006"
[languages.fa]
languageDirection = "rtl"
languageName ="فارسی"
contentDir = "content/fa"
title = "اسناد گلدی"
[languages.fa.params]
description = "یک نمونه برای پوسته داکسی"
time_format_default = "2006.01.02"
time_format_blog = "2006.01.02"
[markup]
[markup.goldmark]
[markup.goldmark.parser.attribute]
block = true
[markup.goldmark.renderer]
unsafe = true
[markup.highlight]
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
style = "tango"
# Uncomment if you want your chosen highlight style used for code blocks without a specified language
# guessSyntax = "true"
# Comment out if you don't want the "print entire section" link enabled.
[outputs]
section = ["HTML", "print", "RSS"]
# Everything below this are Site Params
[params]
privacy_policy = "https://policies.google.com/privacy"
# First one is picked as the Twitter card image if not set on page.
# images = ["images/project-illustration.png"]
# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"
# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version = false
# The version number for the version of the docs represented in this doc set.
# Used in the "version-banner" partial to display a version number for the
# current doc set.
version = "0.7.1"
# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version = "https://example.com"
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
github_repo = "https://github.com/google/docsy-example"
# An optional link to a related project repo. For example, the sibling repository where your product code lives.
github_project_repo = "https://github.com/google/docsy"
# Specify a value here if your content directory is not in your repo's root directory
# github_subdir = ""
# Uncomment this if your GitHub repo does not have "main" as the default branch,
# or specify a new value if you want to reference another branch in your GitHub links
github_branch= "main"
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id = "d72aa9b2712488cc3"
# Enable Lunr.js offline search
offlineSearch = false
# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting = false
[params.copyright]
authors = "Docsy Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | "
from_year = 2018
# User interface configuration
[params.ui]
# Set to true to disable breadcrumb navigation.
breadcrumb_disable = false
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
navbar_logo = true
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
navbar_translucent_over_cover_disable = false
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable = false
# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
# add "hide_feedback: true" to the page's front matter.
[params.ui.feedback]
enable = true
# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
yes = 'Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
no = 'Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.'
# Adds a reading time to the top of each doc.
# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
[params.ui.readingtime]
enable = false
[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
[[params.links.user]]
name = "User mailing list"
url = "https://example.org/mail"
icon = "fa fa-envelope"
desc = "Discussion and help from your fellow users"
[[params.links.user]]
name ="Twitter"
url = "https://example.org/twitter"
icon = "fab fa-twitter"
desc = "Follow us on Twitter to get the latest news!"
[[params.links.user]]
name = "Stack Overflow"
url = "https://example.org/stack"
icon = "fab fa-stack-overflow"
desc = "Practical questions and curated answers"
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
[[params.links.developer]]
name = "GitHub"
url = "https://github.com/google/docsy"
icon = "fab fa-github"
desc = "Development takes place here!"
[[params.links.developer]]
name = "Slack"
url = "https://example.org/slack"
icon = "fab fa-slack"
desc = "Chat with other project developers"
[[params.links.developer]]
name = "Developer mailing list"
url = "https://example.org/mail"
icon = "fa fa-envelope"
desc = "Discuss development issues around the project"
# hugo module configuration
[module]
# Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace:
# workspace = "docsy.work"
[module.hugoVersion]
extended = true
min = "0.146.0"
[[module.imports]]
path = "github.com/google/docsy"
disable = false

205
docs/hugo.yaml Normal file
View File

@@ -0,0 +1,205 @@
baseURL: https://markbeep.github.io/
title: AudioBookRequest
# cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu
# Language settings
contentDir: content
defaultContentLanguage: en
defaultContentLanguageInSubdir: false
# Useful when translating.
enableMissingTranslationPlaceholders: true
enableRobotsTXT: true
# Will give values to .Lastmod etc.
enableGitInfo: true
# Comment out to disable taxonomies in Docsy
# disableKinds: [taxonomy]
# You can add your own taxonomies
taxonomies:
tag: tags
category: categories
# Highlighting config
pygmentsCodeFences: true
pygmentsUseClasses: false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic: false
# pygmentsOptions: "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle: tango
# Configure how URLs look like per section.
permalinks:
blog: /:section/:year/:month/:day/:slug/
# Image processing configuration.
imaging:
resampleFilter: CatmullRom
quality: 75
anchor: smart
# Language configuration
languages:
en:
languageName: English
title: AudioBookRequest Docs
params:
description:
Documentation for AudioBookRequest, a tool to request audiobooks.
# cSpell:enable
markup:
goldmark:
parser:
attribute:
block: true
renderer:
unsafe: true
highlight:
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
style: doom-one
# Uncomment if you want your chosen highlight style used for code blocks without a specified language
# guessSyntax: true
# Everything below this are Site Params
# Comment out if you don't want the "print entire section" link enabled.
outputs:
section: [HTML, print, RSS]
params:
taxonomy:
# set taxonomyCloud = [] to hide taxonomy clouds
taxonomyCloud: [tags, categories]
# If used, must have same length as taxonomyCloud
taxonomyCloudTitle: [Tag Cloud, Categories]
# set taxonomyPageHeader = [] to hide taxonomies on the page headers
taxonomyPageHeader: [tags, categories]
# privacy_policy: https://policies.google.com/privacy
# First one is picked as the Twitter card image if not set on page.
# images: [images/project-illustration.png]
# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu: Releases
# Flag used in the "version-banner" partial to decide whether to display a
# banner on every page indicating that this is an archived version of the docs.
# Set this flag to "true" if you want to display the banner.
archived_version: false
# The version number for the version of the docs represented in this doc set.
# Used in the "version-banner" partial to display a version number for the
# current doc set.
version: 1.4.8
# A link to latest version of the docs. Used in the "version-banner" partial to
# point people to the main doc site.
url_latest_version: https://example.com
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
github_repo: https://github.com/markbeep/AudioBookRequest
# An optional link to a related project repo. For example, the sibling repository where your product code lives.
github_project_repo: https://github.com/markbeep/AudioBookRequest
# Specify a value here if your content directory is not in your repo's root directory
github_subdir: docs
# Uncomment this if your GitHub repo does not have "main" as the default branch,
# or specify a new value if you want to reference another branch in your GitHub links
github_branch: main
# Google Custom Search Engine ID. Remove or comment out to disable search.
gcs_engine_id: d72aa9b2712488cc3
# Enable Lunr.js offline search
offlineSearch: false
# Enable syntax highlighting and copy buttons on code blocks with Prism
prism_syntax_highlighting: false
copyright:
authors:
markbeep | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) |
from_year: 2025
# User interface configuration
ui:
# Set to true to disable breadcrumb navigation.
breadcrumb_disable: false
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
navbar_logo: true
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
navbar_translucent_over_cover_disable: false
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact: false
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable: false
# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
# add "hide_feedback: true" to the page's front matter.
feedback:
enable: true
# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
'yes': >-
Glad to hear it! Please <a
href="https://github.com/markbeep/AudioBookRequest/issues/new">tell us
how we can improve</a>.
'no': >-
Sorry to hear that. Please <a
href="https://github.com/markbeep/AudioBookRequest/issues/new">tell us
how we can improve</a>.
# Adds a reading time to the top of each doc.
# If you want this feature, but occasionally need to remove the Reading time from a single page,
# add "hide_readingtime: true" to the page's front matter
readingtime:
enable: false
showLightDarkModeMenu: true
links:
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
user:
# - name: User mailing list
# url: https://example.org/mail
# icon: fa fa-envelope
# desc: Discussion and help from your fellow users
# - name: Twitter
# url: https://example.org/twitter
# icon: fab fa-twitter
# desc: Follow us on Twitter to get the latest news!
# - name: Stack Overflow
# url: https://example.org/stack
# icon: fab fa-stack-overflow
# desc: Practical questions and curated answers
- name: Discord
url: https://discord.gg/SsFRXWMg7s
icon: fab fa-discord
desc: Chat with others and get support here!
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
developer:
- name: GitHub
url: https://github.com/google/docsy
icon: fab fa-github
desc: Development takes place here!
module:
# Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace:
# workspace: docsy.work
hugoVersion:
extended: true
min: 0.146.0
imports:
- path: github.com/google/docsy
disable: false

7
docs/layouts/404.html Normal file
View File

@@ -0,0 +1,7 @@
{{ define "main" -}}
<div class="td-content">
<h1>Not found</h1>
<p>Oops! This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">home page</a>.</p>
<p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p>
</div>
{{- end }}

1
docs/layouts/_markup/render-heading.html Normal file
View File

@@ -0,0 +1 @@
{{ partial "td/render-heading.html" . }}

52
docs/package.json Normal file
View File

@@ -0,0 +1,52 @@
{
"name": "docsy-example-site",
"version": "0.12.0",
"version.next": "0.12.1-dev-unreleased",
"description": "Example site that uses Docsy theme for technical documentation.",
"repository": "github:google/docsy-example",
"homepage": "https://example.docsy.dev",
"author": "Docsy Authors",
"license": "Apache-2.0",
"bugs": "https://github.com/google/docsy-example/issues",
"spelling": "cSpell:ignore docsy hugo htmltest precheck postbuild rtlcss -",
"scripts": {
"_build": "npm run _hugo-dev --",
"_check:links": "echo IMPLEMENTATION PENDING for check-links; echo",
"_hugo": "hugo --cleanDestinationDir",
"_hugo-dev": "npm run _hugo -- -e dev -DFE",
"_local": "npx cross-env HUGO_MODULE_WORKSPACE=docsy.work",
"_serve": "npm run _hugo-dev -- --minify serve --renderToMemory",
"build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"",
"build:production": "npm run _hugo -- --minify",
"build": "npm run _build -- ",
"check:links:all": "HTMLTEST_ARGS= npm run _check:links",
"check:links": "npm run _check:links",
"clean": "rm -Rf public/* resources",
"local": "npm run _local -- npm run",
"make:public": "git init -b main public",
"precheck:links:all": "npm run build",
"precheck:links": "npm run build",
"postbuild:preview": "npm run _check:links",
"postbuild:production": "npm run _check:links",
"serve": "npm run _serve",
"test": "npm run check:links",
"update:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest",
"update:hugo": "npm install --save-dev --save-exact hugo-extended@latest",
"update:pkgs": "npx npm-check-updates -u"
},
"devDependencies": {
"autoprefixer": "^10.4.21",
"cross-env": "^7.0.3",
"hugo-extended": "0.147.6",
"postcss-cli": "^11.0.1",
"rtlcss": "^4.3.0"
},
"optionalDependencies": {
"npm-check-updates": "^18.0.1"
},
"private": true,
"prettier": {
"proseWrap": "always",
"singleQuote": true
}
}

24
flake.lock generated
View File

@@ -20,11 +20,11 @@
},
"nixpkgs": {
"locked": {
"lastModified": 1743448293,
"narHash": "sha256-bmEPmSjJakAp/JojZRrUvNcDX2R5/nuX6bm+seVaGhs=",
"lastModified": 1749285348,
"narHash": "sha256-frdhQvPbmDYaScPFiCnfdh3B/Vh81Uuoo0w5TkWmmjU=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "77b584d61ff80b4cef9245829a6f1dfad5afdfa3",
"rev": "3e3afe5174c561dee0df6f2c2b2236990146329f",
"type": "github"
},
"original": {
@@ -47,11 +47,11 @@
]
},
"locked": {
"lastModified": 1742689179,
"narHash": "sha256-kDXV6r6pQp6sxBKKxXqcTGPdiH63m8WA+IvzHhdZlEg=",
"lastModified": 1748562898,
"narHash": "sha256-STk4QklrGpM3gliPKNJdBLSQvIrqRuwHI/rnYb/5rh8=",
"owner": "pyproject-nix",
"repo": "build-system-pkgs",
"rev": "5c2a1faadc4015d50eb9919a8e20c112f3765fc2",
"rev": "33bd58351957bb52dd1700ea7eeefe34de06a892",
"type": "github"
},
"original": {
@@ -67,11 +67,11 @@
]
},
"locked": {
"lastModified": 1743438845,
"narHash": "sha256-1GSaoubGtvsLRwoYwHjeKYq40tLwvuFFVhGrG8J9Oek=",
"lastModified": 1746540146,
"narHash": "sha256-QxdHGNpbicIrw5t6U3x+ZxeY/7IEJ6lYbvsjXmcxFIM=",
"owner": "pyproject-nix",
"repo": "pyproject.nix",
"rev": "8063ec98edc459571d042a640b1c5e334ecfca1e",
"rev": "e09c10c24ebb955125fda449939bfba664c467fd",
"type": "github"
},
"original": {
@@ -114,11 +114,11 @@
]
},
"locked": {
"lastModified": 1743583530,
"narHash": "sha256-H1QTqUtASQL1wTKEOS+sCUedu2CQ0PvU7/Elqg1jIhw=",
"lastModified": 1749170547,
"narHash": "sha256-zOptuFhTr9P0A+unFaOBFx5E5T6yx0qE8VrUGVrM96U=",
"owner": "pyproject-nix",
"repo": "uv2nix",
"rev": "ffb8844276870057f85a09dcb8f4e0fab00528e7",
"rev": "7ae60727d4fc2e41aefd30da665e4f92ba8298f1",
"type": "github"
},
"original": {

3
flake.nix
View File

@@ -150,11 +150,12 @@
devShells.default = pkgs.mkShell {
venvDir = ".venv";
packages = with pkgs; [
nodejs_23
nodejs_24
sqlite
nodePackages.browser-sync
python312Packages.venvShellHook
uv
hugo
];
postShellHook = "uv sync";
};