docs: Organize readme and fix doc links (#2479)
Resolves https://github.com/webrecorder/browsertrix/issues/2478 ## Changes - Organizes README - Fixes relative links in mkdocs --------- Co-authored-by: Tessa Walsh <tessa@bitarchivist.net>
This commit is contained in:
sua yoo
GitHub
parent
b2c5b9bc59
commit
bcb73932d4
27
CHANGES.md
27
CHANGES.md
@ -1,27 +0,0 @@
|
||||
### v1.3.0
|
||||
|
||||
See: https://github.com/webrecorder/browsertrix-cloud/releases/tag/v1.3.0 for latest release notes.
|
||||
|
||||
### v1.2.0
|
||||
|
||||
See: https://github.com/webrecorder/browsertrix-cloud/releases/tag/v1.2.0 for latest release notes.
|
||||
|
||||
### v1.1.0
|
||||
|
||||
New Features:
|
||||
- Viewing crawl queue and dynamically adding exclusions to crawl queue while crawl is running.
|
||||
- Adding exclusions to crawl config screen.
|
||||
- Setting initial browser language on crawl config.
|
||||
|
||||
Mkdocs based documentation added
|
||||
|
||||
Docker swarm / compose / podman-based deployments now deprecated in favor of Kubernetes
|
||||
|
||||
Various UI improvements and tweaks
|
||||
|
||||
|
||||
### v1.0.0
|
||||
|
||||
Initial release
|
||||
|
||||
|
||||
42
README.md
42
README.md
@ -8,42 +8,54 @@
|
||||
|
||||
Browsertrix is a cloud-native, high-fidelity, browser-based crawling service designed to make web archiving easier and more accessible for everyone.
|
||||
|
||||
The service provides an API and UI for scheduling crawls and viewing results, and managing all aspects of crawling process. This system provides the orchestration and management around crawling, while the actual crawling is performed using [Browsertrix Crawler](https://github.com/webrecorder/browsertrix-crawler) containers, which are launched for each crawl.
|
||||
The service provides an API and UI for starting, scheduling, sharing, and managing crawls. This repo includes the orchestration and management tools around crawling, while the actual crawling is performed using [browsertrix-crawler](https://github.com/webrecorder/browsertrix-crawler) containers.
|
||||
|
||||
See [webrecorder.net/browsertrix](https://webrecorder.net/browsertrix) for a feature overview and information about how to sign up for Webrecorder's hosted Browsertrix service.
|
||||
Install Browsertrix to self host, or access hosted Browsertrix from [app.browsertrix.com](https://app.browsertrix.com).
|
||||
|
||||
See [webrecorder.net/browsertrix](https://webrecorder.net/browsertrix/) for a full overview of features.
|
||||
|
||||
## Documentation
|
||||
|
||||
The full docs for using, deploying, and developing Browsertrix are available at [docs.browsertrix.com](https://docs.browsertrix.com).
|
||||
Documentation for using, deploying, and developing Browsertrix is available at [docs.browsertrix.com](https://docs.browsertrix.com).
|
||||
|
||||
Our docs are created with [Material for MKDocs](https://squidfunk.github.io/mkdocs-material/).
|
||||
See instructions in [frontend/docs](./frontend/docs/docs/develop/docs.md#installation) to run the docs locally.
|
||||
|
||||
## Deployment
|
||||
## Installation
|
||||
|
||||
The latest deployment documentation is available at [docs.browsertrix.com/deploy](https://docs.browsertrix.com/deploy).
|
||||
Instructions for setting up Browsertrix is available at [docs.browsertrix.com/deploy](https://docs.browsertrix.com/deploy).
|
||||
|
||||
The docs cover deploying Browsertrix in different environments using Kubernetes, from a single-node setup to scalable clusters in the cloud.
|
||||
|
||||
Early on, Browsertrix also supported Docker Compose and podman-based deployment. This was deprecated due to the complexity of maintaining feature parity across different setups, and with various Kubernetes deployment options being available and easy to deploy, even on a single machine.
|
||||
## Support
|
||||
|
||||
Making deployment of Browsertrix as easy as possible remains a key goal, and we welcome suggestions for how we can further improve our Kubernetes deployment options.
|
||||
Ask us your questions about Browsertrix and web archiving in the [community help forum](https://forum.webrecorder.net/c/help/5).
|
||||
|
||||
If you are looking to just try running a single crawl, you may want to try [Browsertrix Crawler](https://github.com/webrecorder/browsertrix-crawler) first to test out the crawling capabilities.
|
||||
Dedicated professional support is available with a custom subscription. For details, see [hosted Browsertrix plans](https://webrecorder.net/browsertrix/#get-started).
|
||||
|
||||
## Bugs
|
||||
|
||||
For bug reports or feature requests, please open a [GitHub issue](https://github.com/webrecorder/browsertrix/issues/new/choose).
|
||||
|
||||
## Changelog
|
||||
|
||||
See [release notes](https://github.com/webrecorder/browsertrix/releases).
|
||||
|
||||
## Contributing
|
||||
|
||||
Though the system and backend API is fairly stable, we are working on many additional features. Please see the GitHub issues and [this GitHub Project](https://github.com/orgs/webrecorder/projects/9) for our current project plan and tasks.
|
||||
### Developing
|
||||
|
||||
Guides for getting started with local development are available at [docs.browsertrix.com/develop](https://docs.browsertrix.com/develop/).
|
||||
Guides for getting started with local development are available at [docs.browsertrix.com/develop](https://docs.browsertrix.com/develop).
|
||||
|
||||
### Translation
|
||||
See [Code of Conduct](https://github.com/webrecorder/browsertrix?tab=coc-ov-file#contributor-covenant-code-of-conduct).
|
||||
|
||||
We use [Weblate](https://hosted.weblate.org/engage/browsertrix/) to manage translation contributions.
|
||||
### Translating
|
||||
|
||||
Translations are managed through Weblate, a web-based and open source translation tool. View translations in progress and register to contribute at [our Weblate project](https://hosted.weblate.org/engage/browsertrix/).
|
||||
|
||||
<img src="https://hosted.weblate.org/widget/browsertrix/browsertrix-ui/multi-auto.svg" alt="Translation status" />
|
||||
|
||||
## License
|
||||
|
||||
Browsertrix is made available under the AGPLv3 License.
|
||||
Browsertrix is made available under the [AGPLv3 License](https://github.com/webrecorder/browsertrix?tab=AGPL-3.0-1-ov-file#readme).
|
||||
|
||||
Documentation is made available under the Creative Commons Attribution 4.0 International License
|
||||
Documentation is made available under the Creative Commons Attribution 4.0 International License.
|
||||
@ -2,35 +2,52 @@
|
||||
|
||||
Our documentation is built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and configured via `mkdocs.yml` in the project root.
|
||||
|
||||
The docs can be found in the `./docs` subdirectory.
|
||||
The docs can be found in the `frontend/docs` subdirectory.
|
||||
|
||||
To build the docs locally, install Material for MkDocs with pip, pipx, or uvx:
|
||||
## Installation
|
||||
|
||||
First, change your working directory to `frontend/docs`. Then, to run the docs locally:
|
||||
|
||||
=== "pip"
|
||||
|
||||
Install Material for MkDocs:
|
||||
|
||||
```sh
|
||||
pip install mkdocs-material
|
||||
```
|
||||
|
||||
Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site.
|
||||
Start the docs development server:
|
||||
|
||||
```sh
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
=== "pipx"
|
||||
|
||||
Install Material for MkDocs:
|
||||
|
||||
```sh
|
||||
pipx install mkdocs-material --include-deps
|
||||
```
|
||||
|
||||
Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site.
|
||||
Start the docs development server:
|
||||
|
||||
```sh
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
=== "uvx"
|
||||
|
||||
From `frontend/docs`:
|
||||
Install and start the docs development server:
|
||||
|
||||
```sh
|
||||
uvx --with mkdocs-material mkdocs serve
|
||||
```
|
||||
|
||||
The docs hosted on [docs.browsertrix.com](https://docs.browsertrix.com) may be different from the main branch of [github.com/webrecorder/browsertrix](https://github.com/webrecorder/browsertrix). They are updated by running the [publish docs GitHub workflow](https://github.com/webrecorder/browsertrix/actions/workflows/docs-publish.yaml), typically alongside a release.
|
||||
You can now view a local version of the docs at [localhost:8000](http://localhost:8000).
|
||||
|
||||
??? "Differences between self-hosted and Webrecorder hosted docs"
|
||||
The docs available online at [docs.browsertrix.com](https://docs.browsertrix.com) may differ from the main branch of [github.com/webrecorder/browsertrix](https://github.com/webrecorder/browsertrix). The online documentation corresponds to the latest hosted Browsertrix production release.
|
||||
|
||||
## Adding New Pages
|
||||
|
||||
|
||||
@ -62,7 +62,7 @@ The **WACZ Files** tab lists the individually downloadable WACZ files that make
|
||||
|
||||
To download an entire archived item as a single WACZ file, click the _Download Item_ button at the top of the **WACZ Files** tab or the _Download Item_ entry in the crawl's _Actions_ menu.
|
||||
|
||||
To combine multiple archived items and download them all as a single WACZ file, add them to a collection and [download the collection](collection.md#downloading-collections).
|
||||
To combine multiple archived items and download them all as a single WACZ file, add them to a collection and [download the collection](collection.md#download-a-collection).
|
||||
|
||||
### Error Logs
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ A crawl workflow can also be set to [automatically add any completed crawls to a
|
||||
|
||||
### Customize a Collection
|
||||
|
||||
The [Presentation and Sharing](../presentation-sharing) page provides further details for options on how to present and share Collections. You can customize how your Collection appears to the public by clicking the edit button :bootstrap-pencil: in each collection to:
|
||||
The [Presentation and Sharing](./presentation-sharing.md) page provides further details for options on how to present and share Collections. You can customize how your Collection appears to the public by clicking the edit button :bootstrap-pencil: in each collection to:
|
||||
|
||||
- **Name** it and add a **description** — include emojis if that’s your style 😉
|
||||
|
||||
@ -42,4 +42,4 @@ Collections can be set to one of the one following access modes.
|
||||
- Public — Collections can be shared with others, and when enabled, collections can also be listed in the [public collections gallery](org-settings.md#public-collections-gallery).
|
||||
|
||||
!!! tip "Note: About Public Collections Gallery"
|
||||
If the public collections gallery page is not enabled, any existing public collections are treated the same as unlisted collections. Check out [enabling public collection gallery](../public-collections-gallery) for a guide on how to enable this page.
|
||||
If the public collections gallery page is not enabled, any existing public collections are treated the same as unlisted collections. Check out [enabling public collection gallery](./public-collections-gallery.md) for a guide on how to enable this page.
|
||||
|
||||
@ -47,7 +47,7 @@ If you don’t have any public Collections yet, on the right side of the section
|
||||
|
||||
### Remove Collections
|
||||
|
||||
You'll take similar steps from [Add Collections](../public-collections-gallery/#add-collections) to also remove Collections from the Public Collections Gallery
|
||||
You'll take similar steps from [Add Collections](./public-collections-gallery.md#add-collections) to also remove Collections from the Public Collections Gallery
|
||||
|
||||
1. Within the Public Collections Gallery, click the edit button :bootstrap-pencil: on the specific Collection you want to remove
|
||||
|
||||
@ -56,7 +56,7 @@ You'll take similar steps from [Add Collections](../public-collections-gallery/#
|
||||
|
||||
### Customize Collections
|
||||
|
||||
The [Presentation and Sharing](../presentation-sharing) page provides further details for options on how to present and share Collections in your Public Collections Gallery. Your Public Collection Gallery page will automatically have the title of your org. You can customize this page by including a **Description** and your org's **Website** by adding them from your org's **Settings** of your account.
|
||||
The [Presentation and Sharing](./presentation-sharing.md) page provides further details for options on how to present and share Collections in your Public Collections Gallery. Your Public Collection Gallery page will automatically have the title of your org. You can customize this page by including a **Description** and your org's **Website** by adding them from your org's **Settings** of your account.
|
||||
|
||||
### Description
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user