From 9e581cbb7dee7390b8d40da225bf9a0fa2fbbff2 Mon Sep 17 00:00:00 2001 From: sua yoo Date: Tue, 3 Jun 2025 13:38:51 -0700 Subject: [PATCH] fix: Improve embedded user guide UX (#2630) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves https://github.com/webrecorder/browsertrix/issues/2629 ## Changes - Fixes user guide not opening to the correct page when not using the workflow editor - Fixes out of date instructions in "starting a crawl" user guide - Updates user guide so that the content makes more sense for both logged in and non-logged in users, including moving the introduction section so that the user guide navigation categories are all displayed (see screenshot) ## Screenshots | Page | Image/video | | ---- | ----------- | | Dashboard | Screenshot 2025-05-27 at 5 09 07 PM | --------- Co-authored-by: Emma Segal-Grossman --- .../docs/docs/user-guide/getting-started.md | 22 +++++----- frontend/docs/docs/user-guide/index.md | 2 +- frontend/docs/docs/user-guide/signup.md | 6 ++- frontend/docs/mkdocs.yml | 2 +- .../crawl-workflows/workflow-editor.ts | 2 +- frontend/src/index.ts | 42 ++++++++++++------- frontend/src/utils/workflow.ts | 2 +- 7 files changed, 49 insertions(+), 29 deletions(-) diff --git a/frontend/docs/docs/user-guide/getting-started.md b/frontend/docs/docs/user-guide/getting-started.md index 29439d78..4374611b 100644 --- a/frontend/docs/docs/user-guide/getting-started.md +++ b/frontend/docs/docs/user-guide/getting-started.md @@ -2,24 +2,26 @@ Let’s crawl your first webpage! Start by opening up a webpage that you'd like to crawl, and note the URL for later. -## Logging in +## Accessing your dashboard -To start crawling with hosted Browsertrix, you'll need a Browsertrix account. [Sign up for an account](./signup.md) and log in. +To start a crawl, you'll need to log in using a Browsertrix account that has [**crawler** permissions](./org-members.md#permission-levels). -!!! note "Self-hosting" +You likely have crawler permissions already if: - If you'd like to try Browsertrix before signing up, or you have specialized hosting requirements, you can host Browsertrix yourself. [Set up Browsertrix](../deploy/index.md) on your system and log in as your admin user. +- You [registered for an org on hosted Browsertrix](./signup.md) +- You [joined an existing org](./join.md) and were given crawler permissions +- You are the admin of a self-hosted instance + +Check if you have crawler permissions by logging in. If you see a _+ Create New..._ button near the org name, you're able to start a crawl. If you don't see this button and think that you should, contact your org admin to update your permissions. ## Starting the crawl -Once you've logged in you should see your org [overview](overview.md). If you land somewhere else, navigate to **Dashboard**. +When you log in, the first page you see is the [org dashboard](overview.md). If you've navigated away to another page, navigate back to **Dashboard**. 1. Tap the _Create New..._ shortcut and select **Crawl Workflow**. -2. Choose **Page List**. We'll get into the details of the options [later](./crawl-workflows.md), but this is a good starting point for a simple crawl. -3. Enter the URL of the webpage that you noted earlier in **Page URL(s)**. -4. Tap _Review & Save_. -5. Tap _Save Workflow_. -6. You should now see your new crawl workflow. Give the crawler a few moments to warm up, and then watch as it archives the webpage! +2. Enter the URL of the webpage that you noted earlier as the **Page URL**. +3. Tap _Run Crawl_. +4. You should now see your new crawl workflow running. Give the crawler a few moments to warm up, and then watch as it archives the webpage! --- diff --git a/frontend/docs/docs/user-guide/index.md b/frontend/docs/docs/user-guide/index.md index 389ef571..7d7d4e41 100644 --- a/frontend/docs/docs/user-guide/index.md +++ b/frontend/docs/docs/user-guide/index.md @@ -1,4 +1,4 @@ -# Welcome +# Introduction Browsertrix is an intuitive, automated web archiving platform designed to allow you to archive, replay, and share websites exactly as they were at a certain point in time. diff --git a/frontend/docs/docs/user-guide/signup.md b/frontend/docs/docs/user-guide/signup.md index 4b073879..f6345151 100644 --- a/frontend/docs/docs/user-guide/signup.md +++ b/frontend/docs/docs/user-guide/signup.md @@ -1,5 +1,9 @@ # Register For an Account +!!! tip "Already have an account?" + + Skip ahead to [running your first crawl](./getting-started.md). + !!! note "Self-hosting?" This guide only applies to hosted Browsertrix accounts. If you're self-hosting Browsertrix, [enable open registration](../deploy/customization.md#enable-open-registration) to allow others to sign up for an account on your instance. @@ -8,7 +12,7 @@ To sign up for Browsertrix, [choose a plan](https://webrecorder.net/browsertrix/ ## Register Your Org -After you finish setting up your subscription, you'll receive an email from us with a link to set up your org (organization.) +After you finish setting up your subscription, you'll receive an email from Webrecorder with a link to set up your org (organization.) Choose an org name that's unique and memorable, like the name of your company or organization. Your org URL identifier will determine the unique URL of the org's home page. diff --git a/frontend/docs/mkdocs.yml b/frontend/docs/mkdocs.yml index 6150c49d..e2cac910 100644 --- a/frontend/docs/mkdocs.yml +++ b/frontend/docs/mkdocs.yml @@ -47,8 +47,8 @@ theme: nav: - Overview: index.md - User Guide: + - user-guide/index.md - Getting Started: - - user-guide/index.md - user-guide/signup.md - user-guide/getting-started.md - Orgs: diff --git a/frontend/src/features/crawl-workflows/workflow-editor.ts b/frontend/src/features/crawl-workflows/workflow-editor.ts index 0a1271c9..fabf8b36 100644 --- a/frontend/src/features/crawl-workflows/workflow-editor.ts +++ b/frontend/src/features/crawl-workflows/workflow-editor.ts @@ -2247,7 +2247,7 @@ https://archiveweb.page/images/${"logo.svg"}`} "btrix-user-guide-show", { detail: { - path: `user-guide/workflow-setup/#${workflowTabToGuideHash[step]}`, + path: `workflow-setup/#${workflowTabToGuideHash[step]}`, }, bubbles: true, composed: true, diff --git a/frontend/src/index.ts b/frontend/src/index.ts index e6ba75af..1a019fb0 100644 --- a/frontend/src/index.ts +++ b/frontend/src/index.ts @@ -103,7 +103,7 @@ export class App extends BtrixElement { private viewState!: ViewState; @state() - private fullDocsUrl = "/docs/"; + private userGuidePath = ""; @state() private globalDialogContent: DialogContent = {}; @@ -199,7 +199,7 @@ export class App extends BtrixElement { "btrix-user-guide-show", (e: UserGuideEventMap["btrix-user-guide-show"]) => { e.stopPropagation(); - this.showUserGuide(e.detail.path); + void this.showUserGuide(e.detail.path); }, ); } @@ -385,6 +385,16 @@ export class App extends BtrixElement { >${this.globalDialogContent.body} + ${this.renderUserGuide()} + `; + } + + private renderUserGuide() { + if (!this.docsUrl) return; + + const url = `${this.docsUrl}user-guide/${this.userGuidePath}`; + + return html` -1) { + iframe.src = src.slice(0, src.indexOf("#")); + } }} > - + ${msg("User Guide")} @@ -535,7 +549,7 @@ export class App extends BtrixElement { ? html`