Frontend hosted-docs (#2107)

Fixes #2106 

Docs are now hosted as part of the frontend at `/docs` by default.

- If `docs_url` is set in the helm chart, the `/docs` endpoint will
redirect to that endpoint instead
- Use multi-stage python image to build mkdocs as part of frontend, then
copy static output
- Dir layout: mkdocs.yml and docs into frontend/docs
- CI: Update docs build GH action to use new path
- Update all frontend paths to use `/docs/` instead of
`https://docs.browsertrix.com/`

---------
Co-authored-by: Henry Wilkinson <henry@wilkinson.graphics>

.github/workflows/docs-publish.yaml

@@ -19,6 +19,6 @@ jobs:
       - run: pip install mkdocs-material requests pyyaml
 
       - name: Generate Helm Chart Index
-        run: python ./scripts/generate-helm-index.py > ./docs/helm-repo/index.yaml
+        run: python ./scripts/generate-helm-index.py > ./frontend/docs/docs/helm-repo/index.yaml
 
-      - run: mkdocs gh-deploy --force
+      - run: cd frontend/docs; mkdocs gh-deploy --force

chart/templates/frontend.yaml

@@ -49,6 +49,11 @@ spec:
             - name: RWP_BASE_URL
               value: {{ .Values.rwp_base_url }}
 
+            {{- if .Values.docs_url }}
+            - name: DOCS_URL
+              value: {{ .Values.docs_url }}
+            {{- end }}
+
             {{- if .Values.minio_local }}
             - name: LOCAL_MINIO_HOST
               value: "{{ .Values.minio_host }}"

chart/values.yaml

@@ -156,6 +156,11 @@ local_service_port: 30870
 
 frontend_alias: "http://browsertrix-cloud-frontend"
 
+# custom URL for where Browsertrix docs are hosted
+# by default, docs are served from /docs/ but can be served from a custom
+# URL specified here.
+# docs_url: "https://browsertrix-docs.example.com/"
+
 # Autoscaling
 # -----------
 # max number of backend pods to scale to

docs/overrides/main.html

@@ -1,6 +0,0 @@
-{% extends "base.html" %}
-
-{% block icons %}
-  {% set icon_path = "overrides/.icons/bootstrap/" %}
-  {{ super() }}
-{% endblock %}

docs/stylesheets/extra.css

@@ -1,188 +0,0 @@
-/* Font style definitions */
-
-@font-face {
-    font-family: 'Recursive';
-    font-style: oblique 0deg 15deg;
-    font-weight: 300 1000;
-    src: url('../assets/fonts/Recursive_VF_1.084.woff2') format('woff2');
-    font-feature-settings: "ss12";
-}
-
-@font-face {
-    font-family: 'Inter';
-    font-weight: 100 900;
-    font-display: swap;
-    font-style: normal;
-    src: url('../assets/fonts/Inter.var.woff2') format('woff2');
-    font-feature-settings: "ss03";
-}
-
-@font-face {
-    font-family: 'Inter';
-    font-weight: 100 900;
-    font-display: swap;
-    font-style: italic;
-    src: url('../assets/fonts/Inter-Italic.var.woff2') format('woff2');
-    font-feature-settings: "ss03";
-}
-
-@font-face {
-    font-family: 'Konsole';
-    font-weight: 100 900;
-    font-display: swap;
-    font-style: normal;
-    src: url('https://wr-static.sfo3.cdn.digitaloceanspaces.com/fonts/konsole/Konsolev1.1-VF.woff2') format('woff2');
-}
-  
-:root {
-    --md-display-font: "Konsole", "Helvetica", sans-serif;
-    --md-code-font: "Recursive", monospace;
-    --md-text-font: "Inter", "Helvetica", "Arial", sans-serif;
-    --wr-blue-primary: #088eaf;
-    --wr-orange-primary: #bb4a00;
-}
-
-[data-md-color-scheme="webrecorder"] {
-    --md-primary-fg-color: #4D7C0F;
-    --md-primary-fg-color--light: #057894;
-    --md-primary-fg-color--dark: #035b71;
-    --md-typeset-color: black;
-    --md-accent-fg-color: #057894;
-    --md-typeset-a-color: #035b71;
-    --md-code-bg-color: #F9FAFB;
-  }
-
-/* Nav changes */
-
-.md-header__title, .md-nav__title {
-    font-family: var(--md-display-font);
-    text-transform: uppercase;
-    font-variation-settings: "wght" 750, "wdth" 87;
-    margin-left: 0 !important;
-}
-
-.md-header__title--active {
-    font-family: var(--md-display-font);
-    text-transform: none;
-    font-variation-settings: "wght" 550, "wdth" 90;
-}
-
-.md-header__button {
-    margin-right: 0 !important;
-}
-
-/* Custom menu item hover */
-
-.md-tabs__link {
-    font-family: var(--md-code-font);
-    font-weight: 400;
-    opacity: .9;
-    transition: .4s cubic-bezier(.1,.7,.1,1),opacity .25s
-}
-
-.md-tabs__link:hover {
-    font-weight: 600;
-}
-
-/* Custom body typography rules */
-
-.md-typeset a {
-    text-decoration: underline;
-}
-
-.headerlink {
-    text-decoration: none!important;
-}
-
-code, pre, kbd {
-    font-variation-settings: "MONO" 1;
-    font-feature-settings: "ss01", "ss02", "ss08";
-}
-
-code {
-    border-width: 1px;
-    border-color: #D1D5DB;
-    border-style: solid;
-}
-
-.md-typeset h1, h2, h3, h4, h5 {
-    color: black;
-}
-
-.md-typeset h1, h2, h3 {
-    font-weight: 650 !important;
-    font-variation-settings: "OPSZ" 35;
-}
-
-/* Custom badge classes, applies custom overrides to inline-code blocks */
-
-.badge-blue {
-    background-color: var(--wr-blue-primary) !important;
-    border-color: var(--wr-blue-primary) !important;
-    color: white !important;
-    font-family: var(--md-text-font);
-    font-weight: 600;
-}
-
-.badge-green {
-    background-color: hsl(142 76% 36%) !important;
-    border-color: hsl(142 76% 36%) !important;
-    color: white !important;
-    font-family: var(--md-text-font);
-    font-weight: 600;
-}
-
-.badge-orange {
-    background-color: var(--wr-orange-primary) !important;
-    border-color: var(--wr-orange-primary) !important;
-    color: white !important;
-    font-family: var(--md-text-font);
-    font-weight: 600;
-}
-
-/* Status Styling */
-
-.status-success {
-    font-family: var(--md-code-font);
-    font-weight: 500;
-    white-space: nowrap;
-    & svg {
-        color: hsl(142.1 76.2% 36.3%);
-    }
-}
-
-.status-neutral {
-    font-family: var(--md-code-font);
-    font-weight: 500;
-    white-space: nowrap;
-    & svg {
-        color: hsl(32.1 94.6% 43.7%);
-    }
-}
-
-.status-warning {
-    font-family: var(--md-code-font);
-    font-weight: 500;
-    white-space: nowrap;
-    & svg {
-        color: hsl(21, 90%, 48%);
-    }
-}
-
-.status-danger {
-    font-family: var(--md-code-font);
-    font-weight: 500;
-    white-space: nowrap;
-    & svg {
-        color: hsl(0 72.2% 50.6%);
-    }
-}
-
-.status-waiting {
-    font-family: var(--md-code-font);
-    font-weight: 500;
-    white-space: nowrap;
-    & svg {
-        color: hsl(271.5 81.3% 55.9%);
-    }
-}

frontend/.eslintrc.js

@@ -138,7 +138,7 @@ module.exports = {
       typescript: true,
     },
   },
-  ignorePatterns: ["__generated__", "__mocks__", "dist"],
+  ignorePatterns: ["__generated__", "__mocks__", "dist", "docs"],
   overrides: [
     {
       extends: ["plugin:@typescript-eslint/disable-type-checked"],

frontend/.prettierignore

@@ -2,3 +2,4 @@ __generated__
 __mocks__
 assets
 dist
+docs

frontend/Dockerfile

@@ -35,10 +35,23 @@ ENV GIT_COMMIT_HASH=${GIT_COMMIT_HASH} \
 RUN yarn build && \
   rm -rf ./node_modules
 
+FROM --platform=$BUILDPLATFORM docker.io/library/python:3.12-slim as build_docs
+
+WORKDIR /docs
+
+RUN pip install mkdocs-material
+
+COPY --link ./docs/mkdocs.yml .
+COPY --link ./docs/docs ./docs
+
+RUN mkdocs build
+
 FROM docker.io/library/nginx:1.23.2
 
 COPY --link --from=build_deps /app/dist /usr/share/nginx/html
 
+COPY --link --from=build_docs /docs/site /usr/share/nginx/html/docs
+
 #COPY ./nginx.conf /etc/nginx/nginx.conf
 COPY --link ./frontend.conf.template /etc/nginx/templates/
 COPY --link ./minio.conf /etc/nginx/includes/

frontend/docs/.gitignore

@@ -0,0 +1 @@
+site

frontend/docs/docs/js/insertversion.js

@@ -25,9 +25,7 @@ function parseVersion(string) {
           node.nodeValue = node.nodeValue.replaceAll("VERSION", version);
         }
       });
-    } catch (e) {
-
-    }
+    } catch (e) {}
   }
 }
 

frontend/docs/docs/overrides/main.html

@@ -0,0 +1,2 @@
+{% extends "base.html" %} {% block icons %} {% set icon_path =
+"overrides/.icons/bootstrap/" %} {{ super() }} {% endblock %}

frontend/docs/docs/stylesheets/extra.css

@@ -0,0 +1,204 @@
+/* Font style definitions */
+
+@font-face {
+  font-family: "Recursive";
+  font-style: oblique 0deg 15deg;
+  font-weight: 300 1000;
+  src: url("../assets/fonts/Recursive_VF_1.084.woff2") format("woff2");
+  font-feature-settings: "ss12";
+}
+
+@font-face {
+  font-family: "Inter";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  src: url("../assets/fonts/Inter.var.woff2") format("woff2");
+  font-feature-settings: "ss03";
+}
+
+@font-face {
+  font-family: "Inter";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: italic;
+  src: url("../assets/fonts/Inter-Italic.var.woff2") format("woff2");
+  font-feature-settings: "ss03";
+}
+
+@font-face {
+  font-family: "Konsole";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  src: url("https://wr-static.sfo3.cdn.digitaloceanspaces.com/fonts/konsole/Konsolev1.1-VF.woff2")
+    format("woff2");
+}
+
+:root {
+  --md-display-font: "Konsole", "Helvetica", sans-serif;
+  --md-code-font: "Recursive", monospace;
+  --md-text-font: "Inter", "Helvetica", "Arial", sans-serif;
+  --wr-blue-primary: #088eaf;
+  --wr-orange-primary: #bb4a00;
+}
+
+[data-md-color-scheme="webrecorder"] {
+  --md-primary-fg-color: #4d7c0f;
+  --md-primary-fg-color--light: #057894;
+  --md-primary-fg-color--dark: #035b71;
+  --md-typeset-color: black;
+  --md-accent-fg-color: #057894;
+  --md-typeset-a-color: #035b71;
+  --md-code-bg-color: #f9fafb;
+}
+
+/* Nav changes */
+
+.md-header__title,
+.md-nav__title {
+  font-family: var(--md-display-font);
+  text-transform: uppercase;
+  font-variation-settings:
+    "wght" 750,
+    "wdth" 87;
+  margin-left: 0 !important;
+}
+
+.md-header__title--active {
+  font-family: var(--md-display-font);
+  text-transform: none;
+  font-variation-settings:
+    "wght" 550,
+    "wdth" 90;
+}
+
+.md-header__button {
+  margin-right: 0 !important;
+}
+
+/* Custom menu item hover */
+
+.md-tabs__link {
+  font-family: var(--md-code-font);
+  font-weight: 400;
+  opacity: 0.9;
+  transition:
+    0.4s cubic-bezier(0.1, 0.7, 0.1, 1),
+    opacity 0.25s;
+}
+
+.md-tabs__link:hover {
+  font-weight: 600;
+}
+
+/* Custom body typography rules */
+
+.md-typeset a {
+  text-decoration: underline;
+}
+
+.headerlink {
+  text-decoration: none !important;
+}
+
+code,
+pre,
+kbd {
+  font-variation-settings: "MONO" 1;
+  font-feature-settings: "ss01", "ss02", "ss08";
+}
+
+code {
+  border-width: 1px;
+  border-color: #d1d5db;
+  border-style: solid;
+}
+
+.md-typeset h1,
+h2,
+h3,
+h4,
+h5 {
+  color: black;
+}
+
+.md-typeset h1,
+h2,
+h3 {
+  font-weight: 650 !important;
+  font-variation-settings: "OPSZ" 35;
+}
+
+/* Custom badge classes, applies custom overrides to inline-code blocks */
+
+.badge-blue {
+  background-color: var(--wr-blue-primary) !important;
+  border-color: var(--wr-blue-primary) !important;
+  color: white !important;
+  font-family: var(--md-text-font);
+  font-weight: 600;
+}
+
+.badge-green {
+  background-color: hsl(142 76% 36%) !important;
+  border-color: hsl(142 76% 36%) !important;
+  color: white !important;
+  font-family: var(--md-text-font);
+  font-weight: 600;
+}
+
+.badge-orange {
+  background-color: var(--wr-orange-primary) !important;
+  border-color: var(--wr-orange-primary) !important;
+  color: white !important;
+  font-family: var(--md-text-font);
+  font-weight: 600;
+}
+
+/* Status Styling */
+
+.status-success {
+  font-family: var(--md-code-font);
+  font-weight: 500;
+  white-space: nowrap;
+  & svg {
+    color: hsl(142.1 76.2% 36.3%);
+  }
+}
+
+.status-neutral {
+  font-family: var(--md-code-font);
+  font-weight: 500;
+  white-space: nowrap;
+  & svg {
+    color: hsl(32.1 94.6% 43.7%);
+  }
+}
+
+.status-warning {
+  font-family: var(--md-code-font);
+  font-weight: 500;
+  white-space: nowrap;
+  & svg {
+    color: hsl(21, 90%, 48%);
+  }
+}
+
+.status-danger {
+  font-family: var(--md-code-font);
+  font-weight: 500;
+  white-space: nowrap;
+  & svg {
+    color: hsl(0 72.2% 50.6%);
+  }
+}
+
+.status-waiting {
+  font-family: var(--md-code-font);
+  font-weight: 500;
+  white-space: nowrap;
+  & svg {
+    color: hsl(271.5 81.3% 55.9%);
+  }
+}

frontend/docs/mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: Browsertrix Docs
 repo_url: https://github.com/webrecorder/browsertrix-cloud/
 repo_name: Browsertrix
-edit_uri: edit/main/docs/
+edit_uri: edit/main/frontend/docs/
 extra_css:
     - stylesheets/extra.css
 extra_javascript:

frontend/frontend.conf.template

@@ -40,6 +40,17 @@ server {
       try_files $uri /index.html;
     }
 
+    location ~* /docs/(.*)$ {
+      set $docs_url "${DOCS_URL}";
+
+      if ($docs_url != "") {
+        return 307 $docs_url$1;
+      }
+
+      root   /usr/share/nginx/html;
+      index  index.html index.htm;
+    }
+
     # serve replay service worker, RWP_BASE_URL set in Dockerfile
     location /replay/sw.js {
       add_header Content-Type application/javascript;

frontend/src/features/crawl-workflows/workflow-editor.ts

@@ -1365,7 +1365,7 @@ https://archiveweb.page/images/${"logo.svg"}`}
             `Increase the number of open browser windows during a crawl. This will speed up your crawl by effectively running more crawlers at the same time.`,
           )}
           <a
-            href="https://docs.browsertrix.com/user-guide/workflow-setup/#browser-windows"
+            href="/docs/user-guide/workflow-setup/#browser-windows"
             class="text-blue-600 hover:text-blue-500"
             target="_blank"
             >${msg("See caveats")}</a

frontend/src/index.ts

@@ -27,7 +27,6 @@ import type { NotifyEventDetail } from "@/controllers/notify";
 import { theme } from "@/theme";
 import { type Auth } from "@/types/auth";
 import { type AppSettings } from "@/utils/app";
-import { tw } from "@/utils/tailwind";
 import brandLockupColor from "~assets/brand/browsertrix-lockup-color.svg";
 
 import "./shoelace";
@@ -67,7 +66,7 @@ export class App extends LiteElement {
   version?: string;
 
   @property({ type: String })
-  docsUrl = "https://docs.browsertrix.com/";
+  docsUrl = "/docs/";
 
   @property({ type: Object })
   settings?: AppSettings;
@@ -78,6 +77,9 @@ export class App extends LiteElement {
   @state()
   private viewState!: ViewState;
 
+  @state()
+  private fullDocsUrl = "/docs/";
+
   @state()
   private globalDialogContent: DialogContent = {};
 
@@ -263,9 +265,15 @@ export class App extends LiteElement {
         </span>
         <iframe
           class="size-full transition-opacity duration-slow"
-          src="${this.docsUrl}/user-guide/"
+          src="${this.docsUrl}user-guide/workflow-setup/"
         ></iframe>
-        <sl-button size="small" slot="footer" variant="text">
+        <sl-button
+          size="small"
+          slot="footer"
+          variant="text"
+          href="${this.fullDocsUrl}"
+          target="_blank"
+        >
           <sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
           ${msg("Open in new window")}</sl-button
         >
@@ -845,21 +853,12 @@ export class App extends LiteElement {
     const iframe = this.userGuideDrawer.querySelector("iframe");
 
     if (iframe) {
-      const oneLoad = () => {
-        iframe.classList.remove(tw`opacity-0`);
-        iframe.removeEventListener("load", oneLoad);
-      };
-
       if (pathName) {
-        if (iframe.src.slice(this.docsUrl.length) !== pathName) {
-          iframe.classList.add(tw`opacity-0`);
-          iframe.addEventListener("load", oneLoad);
-          iframe.src = `${this.docsUrl}${pathName}`;
-        }
+        this.fullDocsUrl = this.docsUrl + pathName;
+        iframe.src = this.fullDocsUrl;
       } else {
-        iframe.classList.add(tw`opacity-0`);
-        iframe.addEventListener("load", oneLoad);
-        iframe.src = this.docsUrl;
+        this.fullDocsUrl = this.docsUrl;
+        iframe.src = this.fullDocsUrl;
       }
 
       void this.userGuideDrawer.show();

frontend/src/pages/invite/ui/inviteMessage.ts

@@ -86,7 +86,7 @@ export const renderInviteMessage = (
               html`Refer to our user guide on
                 <a
                   class="text-neutral-500 underline hover:text-primary"
-                  href="https://docs.browsertrix.com/user-guide/org-settings/"
+                  href="/docs/user-guide/org-settings/"
                   target="_blank"
                   rel="noopener"
                   >org settings</a

frontend/src/pages/org/browser-profiles-new.ts

@@ -76,7 +76,7 @@ export class BrowserProfilesNew extends BtrixElement {
           crawling. For details, refer to
           <a
             class="text-primary hover:text-indigo-400"
-            href="https://docs.browsertrix.com/user-guide/browser-profiles/"
+            href="/docs/user-guide/browser-profiles/"
             target="_blank"
           >
             ${msg("browser profile best practices")}</a

frontend/src/pages/org/workflows-new.ts

@@ -1,6 +1,6 @@
 import { localized, msg } from "@lit/localize";
 import { mergeDeep } from "immutable";
-import { customElement, property, state } from "lit/decorators.js";
+import { customElement, property } from "lit/decorators.js";
 import { ifDefined } from "lit/directives/if-defined.js";
 import { when } from "lit/directives/when.js";
 
@@ -50,7 +50,6 @@ export class WorkflowsNew extends LiteElement {
   @property({ type: Object })
   initialWorkflow?: WorkflowParams;
 
-  @state()
   private userGuideHashLink: GuideHash = "scope";
 
   connectedCallback(): void {
@@ -128,7 +127,7 @@ export class WorkflowsNew extends LiteElement {
                 UserGuideEventMap["btrix-user-guide-show"]["detail"]
               >("btrix-user-guide-show", {
                 detail: {
-                  path: `/user-guide/workflow-setup/#${this.userGuideHashLink}`,
+                  path: `user-guide/workflow-setup/#${this.userGuideHashLink}`,
                 },
                 bubbles: true,
               }),

frontend/webpack.config.js

@@ -31,7 +31,9 @@ const WEBSOCKET_HOST =
 
 const DOCS_URL = process.env.DOCS_URL
   ? new URL(process.env.DOCS_URL)
-  : new URL("https://docs.browsertrix.com/");
+  : isDevServer
+    ? "https://docs.browsertrix.com/"
+    : "/docs/";
 
 // Get git info for release version info
 

frontend/xliff/es.xlf

@@ -2150,13 +2150,6 @@
       <trans-unit id="sf255d6c5d5851c6e">
         <source>Workflows that use this browser profile will behave as if they have logged into the same websites and have the same web cookies.</source>
       </trans-unit>
-      <trans-unit id="hd7ee4df8e7d76865">
-        <source>
-          It is highly recommended to create dedicated accounts to use when
-          crawling. For details, refer to
-          <x equiv-text="&lt;a class=&quot;text-primary hover:text-indigo-400&quot; href=&quot;https://docs.browsertrix.com/user-guide/browser-profiles/&quot; target=&quot;_blank&quot;&gt;&#10;            ${msg(&quot;browser profile best practices&quot;)}&lt;/a&gt;" id="0"/>.
-        </source>
-      </trans-unit>
       <trans-unit id="se058d83e4b3bad9e">
         <source>browser profile best practices</source>
       </trans-unit>
@@ -3199,11 +3192,6 @@
       <trans-unit id="s42e8653d5ae10bc1">
         <source>An org, or organization, is your workspace for web archiving. If you’re archiving collaboratively, an org workspace can be shared between team members.</source>
       </trans-unit>
-      <trans-unit id="hecef9e5e39351b37">
-        <source>Refer to our user guide on
-                <x equiv-text="&lt;a class=&quot;text-neutral-500 underline hover:text-primary&quot; href=&quot;https://docs.browsertrix.com/user-guide/org-settings/&quot; target=&quot;_blank&quot; rel=&quot;noopener&quot;&gt;" id="0"/>org settings<x equiv-text="&lt;/a&gt;" id="1"/>
-                for details.</source>
-      </trans-unit>
       <trans-unit id="s8ae1873b610b92d6">
         <source>Your org dashboard will be
         <x equiv-text="${window.location.protocol}" id="0"/>//<x equiv-text="${window.location.hostname}" id="1"/>/orgs/<x equiv-text="${slug || &quot;&quot;}" id="2"/></source>
@@ -3780,6 +3768,18 @@
       <trans-unit id="sadfb54de733655c9">
         <source>Using proxy: </source>
       </trans-unit>
+      <trans-unit id="habe03840abb41da5">
+        <source>
+          It is highly recommended to create dedicated accounts to use when
+          crawling. For details, refer to
+          <x equiv-text="&lt;a class=&quot;text-primary hover:text-indigo-400&quot; href=&quot;/docs/user-guide/browser-profiles/&quot; target=&quot;_blank&quot;&gt;&#10;            ${msg(&quot;browser profile best practices&quot;)}&lt;/a&gt;" id="0"/>.
+        </source>
+      </trans-unit>
+      <trans-unit id="hda7aa624404fc0ed">
+        <source>Refer to our user guide on
+                <x equiv-text="&lt;a class=&quot;text-neutral-500 underline hover:text-primary&quot; href=&quot;/docs/user-guide/org-settings/&quot; target=&quot;_blank&quot; rel=&quot;noopener&quot;&gt;" id="0"/>org settings<x equiv-text="&lt;/a&gt;" id="1"/>
+                for details.</source>
+      </trans-unit>
     </body>
   </file>
 </xliff>