MKDocs conversion (#278)
Closes #252, Closes #250 ## Changes - ReplayWeb.page uses MKDocs for documentation now! - Requires both [`mkdocs-macros`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) and [`mkdocs-redirects`] (https://github.com/mkdocs/mkdocs-redirects) plugins to be installed - Redirects existing docs pages to their new locations under either `/embedding` or `/user-guide` - Unused images have been removed - Adds new ReplayWeb.page branding! All pages have received copy edits. All references to future (or previously) planned features have been removed. More major content changes of note are as follows: ### Supported Locations - Made into a page, no longer a table. Locations are either supported or not listed. ### Offline Use - Removes browser cache section, adds improved PWA install and uninstall instructions. - Removes navigation instructions to GitHub's releases section in favour of a link ### Supported Formats - Moved to the User Guide homepage - Updated the format support ### Exploring Archives - Example links for showcasing features have been moved to their respective feature documentation section on this page ### Remove Usage, Examples, and Troubleshooting Pages - Usage content is covered in the user guide index - Troubleshooting content has been added to a question section on the getting started page about WARC vs WACZ. - Examples are now Featured Projects on the docs homepage! ### Build Process - Removes Jekyll & related site assets. - Adds new GitHub action for publishing - Adds a python macro to dynamically load the replayweb.page version from package.json - Relocates replayweb.page site content under /site (including docs) - Some assets (favicon, logo) and sw.js/ui.js automatically copied into /site --------- Co-authored-by: Ilya Kreymer <ikreymer@gmail.com>
This commit is contained in:
Henry Wilkinson
co-authored by
Ilya Kreymer
Ilya Kreymer
parent
d276609ffe
commit
a4de740999
@@ -0,0 +1,33 @@
|
||||
# Exploring Archived Content
|
||||
|
||||
The ReplayWeb.page homepage lists an index of all your loaded archived items. Items are searchable by their title or source, and can be filtered by the date they were loaded or their title.
|
||||
|
||||
## Navigation
|
||||
|
||||
ReplayWeb.page's sidebar is the fastest way of finding content within an archived item. It features several tabs that allow information to be accessed:
|
||||
|
||||
### Page
|
||||
|
||||
The pages view lists all the webpages stored within the archived item.
|
||||
|
||||
#### Searching For Pages
|
||||
|
||||
Pages can be searched for by their title, URLs, or extracted text if available.
|
||||
|
||||
ReplayWeb.page will load pre-generated full-text search data when loading WACZ files, and will also attempt to generate full-text index from HTML files contained in WARC files upon loading a WARC.
|
||||
|
||||
### Resources
|
||||
|
||||
The resources view displays all the content within a loaded archived item, listed by URL and media type. For many archived items with no page or curatorial metadata available, this is the best way to explore the archived contents.
|
||||
|
||||
This view is available for all archives that only store raw data.
|
||||
|
||||
#### Searching For Resources
|
||||
|
||||
Page resources can only be searched by URL. Searches can be performed by exact URL, by URL prefix, or by searching for any string contained in the URL.
|
||||
|
||||
The _URL Prefix_ option is best for searching large archives that require on-demand loading. The _Contains_ option will not find any URLs that have not yet been loaded.
|
||||
|
||||
### Story
|
||||
|
||||
The story view presents lists of curated pages and a description of their significance, as specified by the creator of the web archive. This option is only shown if there is a curated story. As curated lists are not a standardized part of the WARC format, only WARCs exported from [Conifer](https://conifer.rhizome.org/) can be configured to use this option.
|
||||
@@ -0,0 +1,28 @@
|
||||
# User Guide
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Check out [Loading Archived Items](loading.md) to point ReplayWeb.page towards the file you wish to view.
|
||||
2. Once your file has been loaded, [learn how to navigate the archived content](exploring.md)!
|
||||
|
||||
## Supported Formats
|
||||
|
||||
While ReplayWeb.page aims to support a variety of formats for archived web content, for best performance we recommend using WACZ files. To archive webpages to WACZ files on a per-page basis, we recommend [ArchiveWeb.page](https://archiveweb.page). If you need to archive entire websites, check out [Browsertrix](https://browsertrix.com).
|
||||
|
||||
??? question "WARC? WACZ? What's the difference?"
|
||||
Due to the nature of the WARC format, the entire file must be read on first use to generate an index — a list of all the pages and content available in the file used by ReplayWebpage to rebuild and display the archived content.
|
||||
|
||||
Inversely, WACZ files are always loaded on-demand and no indexing is required. The initial archive view should load very quickly as a result.
|
||||
|
||||
For users comfortable with the command line, we recommend converting WARC files to WACZ files by using the `wacz` python library, see [py-wacz on GitHub](https://github.com/webrecorder/py-wacz) for more information.
|
||||
|
||||
ReplayWeb.page supports the following file formats listed as "Supported". Format type is determined based on the file's extension.
|
||||
|
||||
| Format | Extensions | Status |
|
||||
|:--------|:--------------------|:---------------|
|
||||
| WACZ | `.wacz` | <span class="status-success">:bootstrap-check-circle-fill: Supported</span> |
|
||||
| WARC | `.warc`, `.warc.gz` | <span class="status-success">:bootstrap-check-circle-fill: Supported</span> |
|
||||
| HAR | `.har` | <span class="status-success">:bootstrap-check-circle-fill: Supported</span> |
|
||||
| WBN | `.wbn` | <span class="status-danger">:bootstrap-x-octagon-fill: Not Supported</span> |
|
||||
| ARC | `.arc` | <span class="status-danger">:bootstrap-x-octagon-fill: Not Supported</span> |
|
||||
| CDX | `.cdx`, `.cdxj` | <span class="status-success">:bootstrap-check-circle-fill: Supported</span> |
|
||||
@@ -0,0 +1,58 @@
|
||||
# Loading Archived Items
|
||||
|
||||
ReplayWeb.page can load archived items from the local filesystem, or from remote locations. If you don't have any archived items yet, try archiving a website with [ArchiveWeb.page](https://archiveweb.page)!
|
||||
|
||||
---
|
||||
|
||||
## Loading Local Files
|
||||
|
||||
From [replayweb.page](https://replayweb.page), press the _Choose File..._ button, pick any local archived item file from your computer, then press _Load_ to start viewing the file's archived content.
|
||||
|
||||
<img alt="screenshot of replayweb.page (online)" src="../../assets/replaywebpage-online-local.png">
|
||||
|
||||
The archived item is loaded directly in the browser and is _not_ uploaded anywhere — your data never leaves your computer!
|
||||
|
||||
Once loaded, the archived item will appear in the list of Loaded Archives and will be identified by its filename with a a `file://` URL as its source. This URL is not shareable as it doesn't exist outside of your computer.
|
||||
|
||||
<figure>
|
||||
<img alt="animated gif of replayweb.page opening an archived item" src="../../assets/replaywebpage-online.gif">
|
||||
<figcaption>Loading an archived item into ReplayWeb.page and viewing a URL in the pages list</figcaption>
|
||||
</figure>
|
||||
|
||||
To unload an archived item, click on the 'X'. Unloading an item does not delete the file from its original location.
|
||||
|
||||
## Loading Files from a URL
|
||||
|
||||
To load an archived item stored in a remote location, enter the URL of the file and press _Load_.
|
||||
|
||||
The archived item will be downloaded, either fully or on-demand (if possible) and presented when ready.
|
||||
|
||||
See the [Supported Locations](locations.md) page for details on supported external sources for serving archived items.
|
||||
|
||||
## Loading Files from Google Drive
|
||||
|
||||
In addition to loading remote content from URLs, ReplayWeb.page also supports loading WARC and WACZ files directly from Google Drive.
|
||||
|
||||
### Add-on Installation
|
||||
|
||||
First, install the [ReplayWeb.page Google Drive Addon](https://gsuite.google.com/u/2/marketplace/app/replaywebpage/160798412227).
|
||||
|
||||
* Press the _Install_ button, Google will walk you through the steps of installation.
|
||||
* Once installed, Google will confirm the install and display where to find ReplayWeb.page in your drive.
|
||||
|
||||
<figure>
|
||||
<img alt="animated gif of replayweb.page google drive add-on install process" src="../../assets/replaywebpage-googledrive-install.gif">
|
||||
<figcaption>Installing the ReplayWeb.page Google Drive add-on</figcaption>
|
||||
</figure>
|
||||
|
||||
### Usage
|
||||
|
||||
1. Navigate to any WARC or WACZ files that available on your Google Drive.
|
||||
|
||||
2. Under the file's _More Actions_ :bootstrap-three-dots-vertical: menu, select _Open With_ and choose _ReplayWeb.page_ from the menu.
|
||||
|
||||
This will redirect to ReplayWeb.page and begin loading the file. Items loaded from Google Drive will have a source URL starting with `googledrive://`.
|
||||
|
||||
---
|
||||
|
||||
Once an archived item has been successfully loaded, the app will display the archive viewer and you can begin exploring your loaded archive.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Supported Location URLs
|
||||
|
||||
ReplayWeb.page uses URLs to uniquely identify web archives.
|
||||
|
||||
In addition HTTP/S, the system supports loading from additional cloud providers and via peer-to-peer decentralized services. The goal is to support loading web archives from any source a web browser can connect to.
|
||||
|
||||
The following is a list of currently supported URL schemes and details below:
|
||||
|
||||
## HTTP and HTTPS
|
||||
|
||||
While `https://replayweb.page` can load archived items from any URL, the hosting server must allow access by [enabling cross origin resource sharing](../embedding/cors-settings.md) (CORS). HTTP URLs may not be accessible from `https://replayweb.page` since it requires HTTPS.
|
||||
|
||||
## Local Files
|
||||
|
||||
Local files selected via the UI file chooser, and will be given a `file://` URL. Unlike other web archive URLs, file URLs can not be shared with others.
|
||||
|
||||
## Amazon S3
|
||||
|
||||
The `s3://` URL scheme is provided as a convenience to reference S3 URLs. The URL is converted to an HTTPS URL for access. The S3 Bucket must be public and also provide access to `https://replayweb.page` via CORS. Downloading via S3 credentials is not currently supported.
|
||||
|
||||
## Google Drive
|
||||
|
||||
The `googledrive://` URL scheme is used when accessing a web archive shared over Google Drive. It provides a unique identifier provided via Google Drive. When accessing a Google Drive URL, users will be asked to authenticate to be able to access the file.
|
||||
|
||||
## IPFS
|
||||
|
||||
The `ipfs://` URL scheme is provided as a convenience and resolves to Cloudflare's IPFS Gateway to download archives from IPFS.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Offline Use
|
||||
|
||||
There are two ways of using ReplayWeb.page without continuous internet access.
|
||||
|
||||
## Progressive Web App
|
||||
|
||||
ReplayWeb.page can be installed as PWA ([Progressive Web App](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)) through supported browsers. Instructions for installation vary based on the browser used to install the application.
|
||||
|
||||
??? question "What's a Progressive Web App?"
|
||||
Progressive Web Apps (PWAs) can be considered cross-platform applications. PWAs are built with the same software used to develop websites, but they also allow developers to access native desktop features to integrate better with desktop operating systems and allow for offline use!
|
||||
|
||||
### Safari
|
||||
|
||||
After navigating to [https://replayweb.page](https://replayweb.page), open the `File` menu and select `Add to Dock`. This will add the PWA to your dock and in Launchpad.
|
||||
|
||||
To uninstall, long press on the app in Launchpad until the icons start to shake, then press the :bootstrap-x: icon.
|
||||
|
||||
### Google Chrome & Microsoft Edge
|
||||
|
||||
After navigating to [https://replayweb.page](https://replayweb.page), look for the installation icon to the left of the bookmark page star in the URL bar. Pressing this icon will display a dialog with an option to install the PWA.
|
||||
|
||||
To uninstall on Edge, navigate to [edge://apps/details/replayweb.page/](edge://apps/details/replayweb.page/) and press `Uninstall`
|
||||
|
||||
To uninstall on Chrome, open the ReplayWeb.page PWA, press the :bootstrap-three-dots-vertical: icon button in the application bar, and select `Uninstall ReplayWeb.page`.
|
||||
|
||||
## Standalone Desktop App
|
||||
|
||||
ReplayWeb.page is also available as a standalone app!
|
||||
|
||||
Navigate to the [latest release of ReplayWeb.page on GitHub](https://github.com/webrecorder/replayweb.page/releases/latest) and download the applicable file for your platform (.dmg for macOS or .exe for Windows).
|
||||
|
||||
The standalone app is useful for two reasons:
|
||||
|
||||
1. Flash is not supported by default in most browsers. The ReplayWeb.page App will continue to bundle [Ruffle](https://ruffle.rs/), a Flash emulator, to continue to make Flash content accessible within archived web content.
|
||||
|
||||
2. If your primary use involves viewing stored locally web archives, the ReplayWeb.page desktop app is a better option, as it provides direct access to the file system. Once loaded, ReplayWeb.page can continue to load web archives from disk without internet access. The desktop app fully replaces [Webrecorder Player](https://github.com/webrecorder/webrecorder-player)
|
||||
|
||||
When using [https://replayweb.page](https://replayweb.page), you may be asked to re-open a local file because a website cannot maintain persistent access to your file system.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Sharing Archived Items
|
||||
|
||||
ReplayWeb.page links are designed to be shareable with others, as long as they have access to the archived item.
|
||||
|
||||
ReplayWeb.page encodes the archived item source and current page parameters in the URL query and hash string. Simply copy the entire location URL, and you can share with others!
|
||||
|
||||
ReplayWeb.page will parse the URL, load the source archived item, then navigate to the current snapshot or search query.
|
||||
|
||||
For example, given the following URL:
|
||||
|
||||
```
|
||||
https://replayweb.page/?source=s3://webrecorder-builds/warcs/netpreserve-twitter.warc#view=replay&url=https%3A%2F%2Ftwitter.com%2Fnetpreserve&ts=20190603053135
|
||||
```
|
||||
|
||||
ReplayWeb.page will load the web archive from `s3://webrecorder-builds/warcs/netpreserve-twitter.warc`, navigate to the correct URL `https://twitter.com/netpreserve` at snapshot `20190603053135`
|
||||
|
||||
The following URL will load the same web archive, and show the search results for pages that contain the word 'WARC':
|
||||
|
||||
```
|
||||
https://replayweb.page/?source=s3://webrecorder-builds/warcs/netpreserve-twitter.warc#view=pages&query=WARC
|
||||
```
|
||||
|
||||
## Can't Share Links to Local Files
|
||||
|
||||
URLs that have a source URL component of `source=file://...` can not be shared as they refer to a local file on your machine. Anyone else attempting to load that URL will get an error.
|
||||
|
||||
## Sharing Archived Items with Google Drive
|
||||
|
||||
Unlike local files, archived items loaded from Google Drive can be shared with others, as long as they have access!
|
||||
|
||||
Files loaded from Google Drive will have a source URL component of `source=googledrive://...`.
|
||||
|
||||
Due to restrictions of Google Drive, users will likely be required to authorize with their Google Account when accessing archived items stored in Google Drive. Public files shared from Google Drive can sometimes be loaded without requiring authorization, but this is only supported for small files.
|
||||
|
||||
To share archived items via Google Drive ensure that the person you are sharing the item with also has the [ReplayWeb.page Google Drive Integration](https://gsuite.google.com/u/2/marketplace/app/replaywebpage/160798412227) installed (see [add-on installation](loading.md#add-on-installation) for details).
|
||||
|
||||
Once they have installed the add-on, share the archived item with them like any other file on Google Drive and have them open it with ReplayWebpage using the [Google Drive loading usage guide](loading.md#usage).
|
||||
Reference in New Issue
Block a user