[Docs]: Fix edit URLs and update instructions for running docs locally (

#2161) - Adds a missing `/docs` to the docs edit urls - Adds instructions for installing `mkdocs-material` with pipx & uvx, and describes correct place to run `mkdocs serve` from - Fixes edit url, opens in a new tab - Adds Plausible --------- Co-authored-by: Henry Wilkinson <[email protected]>
webrecorder · Nov 19, 2024 · 0cbc279 · 0cbc279
1 parent 2cf75bd
commit 0cbc279
Show file tree

Hide file tree

Showing 4 changed files with 111 additions and 40 deletions.
diff --git a/frontend/docs/docs/develop/docs.md b/frontend/docs/docs/develop/docs.md
@@ -4,15 +4,33 @@ Our documentation is built with [Material for MkDocs](https://squidfunk.github.i
 
 The docs can be found in the `./docs` subdirectory.
 
-To build the docs locally, install Material for MkDocs with pip:
+To build the docs locally, install Material for MkDocs with pip, pipx, or uvx:
 
-```shell
-pip install mkdocs-material
-```
+=== "pip"
+
+    ```sh
+    pip install mkdocs-material
+    ```
+
+    Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site.
+
+=== "pipx"
+
+    ```sh
+    pipx install mkdocs-material --include-deps
+    ```
 
-In the project root directory run `mkdocs serve` to run a local version of the documentation site.
+    Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site.
 
-The docs hosted on [docs.browsertrix.com](https://docs.browsertrix.com) are created from the main branch of [https://github.com/webrecorder/browsertrix](https://github.com/webrecorder/browsertrix)
+=== "uvx"
+
+    From `frontend/docs`:
+
+    ```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.
 
 ## Adding New Pages
 
@@ -42,11 +60,10 @@ In a list of three or more items, the list item proceeding the word "and" should
 
 ##### Example
 
-| Use                           | Don't use                    |
-| ----------------------------- | ---------------------------- |
-| One, two, three, and four.    | One, two, three and four.    |
-| Charles, Ada, and Alan.       | Charles, Ada and Alan.       |
-
+| Use                        | Don't use                 |
+| -------------------------- | ------------------------- |
+| One, two, three, and four. | One, two, three and four. |
+| Charles, Ada, and Alan.    | Charles, Ada and Alan.    |
 
 ### Capitalization of Concepts and Tools
 
@@ -55,15 +72,16 @@ Webrecorder has a number of common nouns that we use in our products. Examples i
 ##### Example
 
 When starting a sentence:
+
 > Archived items consist of one or more...
 
 In the middle of a sentence:
 
 > ...they are omitted from the archived items list page...
 
-Webrecorder's software packages are all proper nouns and should always be capitalized.  Examples include: Browsertrix, ReplayWeb.page, ArchiveWeb.Page, and PYWB. Specific pages such as the Archived Items page should also be capitalized as they are not referencing the concept of archived items and are instead referencing the page in question that happens to share the same name.
+Webrecorder's software packages are all proper nouns and should always be capitalized. Examples include: Browsertrix, ReplayWeb.page, ArchiveWeb.Page, and PYWB. Specific pages such as the Archived Items page should also be capitalized as they are not referencing the concept of archived items and are instead referencing the page in question that happens to share the same name.
 
-### Be Concise, Avoid "You Statements"
+### Be Concise, Avoid "You" Statements
 
 Generally, people don't want to have to read documentation. When writing, try to explain concepts simply and with clear objective language. Do not use "we" to refer to communication between the author and the reader, use "we" to refer to Webrecorder. "You can" or "you may" can be used, but preferably when giving supplemental advice and generally not when providing instructions that should be followed to achieve a successful outcome. Otherwise, avoid spending time referring to the reader, instead tell them what they should know.
 
@@ -113,11 +131,11 @@ Tag the language to be used for syntax highlighting.
 
 ##### Example
 
+````markdown
 ```markdown
- ```markdown
- example markdown code block text
- ```
+example markdown code block text
 ```
+````
 
 For in-line code blocks, syntax highlighting should be added for all code-related usage by adding `#!language` to the start of all in-line code blocks. This is not required for paths or simply highlighting important text using in-line code blocks.
 

diff --git a/frontend/docs/docs/overrides/partials/actions.html b/frontend/docs/docs/overrides/partials/actions.html
@@ -0,0 +1,49 @@
+<!-- Adapted from https://github.com/squidfunk/mkdocs-material/blob/51c9f9acb013836910f8e190ca5041f16f09e643/src/templates/partials/actions.html -->
+
+<!--
+  Copyright (c) 2016-2024 Martin Donath <[email protected]>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Actions -->
+{% if page.edit_url %}
+
+<!-- Edit button -->
+{% if "content.action.edit" in features %}
+<a href="{{ page.edit_url }}" title="{{ lang.t('action.edit') }}" class="md-content__button md-icon" target="_blank">
+  {% set icon = config.theme.icon.edit or "material/file-edit-outline" %}
+  {% include ".icons/" ~ icon ~ ".svg" %}
+</a>
+{% endif %}
+
+<!-- View button -->
+{% if "content.action.view" in features %}
+{% if "/blob/" in page.edit_url %}
+{% set part = "blob" %}
+{% else %}
+{% set part = "edit" %}
+{% endif %}
+<a href="{{ page.edit_url | replace(part, 'raw') }}" title="{{ lang.t('action.view') }}"
+  class="md-content__button md-icon">
+  {% set icon = config.theme.icon.view or "material/file-eye-outline" %}
+  {% include ".icons/" ~ icon ~ ".svg" %}
+</a>
+{% endif %}
+{% endif %}
diff --git a/frontend/docs/docs/overrides/partials/integrations/analytics/custom.html b/frontend/docs/docs/overrides/partials/integrations/analytics/custom.html
@@ -0,0 +1,2 @@
+<script defer data-domain="docs.browsertrix.com" src="https://p.webrecorder.net/js/script.outbound-links.js"></script>
+<script>window.plausible = window.plausible || function () { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
diff --git a/frontend/docs/mkdocs.yml b/frontend/docs/mkdocs.yml
@@ -1,11 +1,11 @@
 site_name: Browsertrix Docs
 repo_url: https://github.com/webrecorder/browsertrix-cloud/
 repo_name: Browsertrix
-edit_uri: edit/main/frontend/docs/
+edit_uri: edit/main/frontend/docs/docs/
 extra_css:
-    - stylesheets/extra.css
+  - stylesheets/extra.css
 extra_javascript:
-    - js/insertversion.js
+  - js/insertversion.js
 theme:
   name: material
   custom_dir: docs/overrides
@@ -47,30 +47,30 @@ nav:
   - Overview: index.md
   - User Guide:
       - Getting Started:
-        - user-guide/index.md
-        - user-guide/signup.md
-        - user-guide/getting-started.md
+          - user-guide/index.md
+          - user-guide/signup.md
+          - user-guide/getting-started.md
       - Orgs:
-        - user-guide/org.md
-        - user-guide/join.md
-        - user-guide/overview.md
+          - user-guide/org.md
+          - user-guide/join.md
+          - user-guide/overview.md
       - Crawling:
-        - user-guide/crawl-workflows.md
-        - user-guide/workflow-setup.md
-        - user-guide/running-crawl.md
+          - user-guide/crawl-workflows.md
+          - user-guide/workflow-setup.md
+          - user-guide/running-crawl.md
       - Archived Items:
-        - user-guide/archived-items.md
-        - user-guide/review.md
-        - user-guide/collections.md
+          - user-guide/archived-items.md
+          - user-guide/review.md
+          - user-guide/collections.md
       - Collections:
-        - user-guide/collection.md
+          - user-guide/collection.md
       - Browser Profiles:
-        - user-guide/browser-profiles.md
+          - user-guide/browser-profiles.md
       - Org Settings:
-        - user-guide/org-settings.md
-        - user-guide/org-members.md
+          - user-guide/org-settings.md
+          - user-guide/org-members.md
       - Account Settings:
-        - user-guide/user-settings.md
+          - user-guide/user-settings.md
       - user-guide/contribute.md
   - Self-Hosting:
       - Overview: deploy/index.md
@@ -79,11 +79,11 @@ nav:
       - deploy/customization.md
       - deploy/proxies.md
       - Ansible:
-        - deploy/ansible/digitalocean.md
-        - deploy/ansible/microk8s.md
-        - deploy/ansible/k3s.md
+          - deploy/ansible/digitalocean.md
+          - deploy/ansible/microk8s.md
+          - deploy/ansible/k3s.md
       - Administration:
-        - deploy/admin/org-import-export.md
+          - deploy/admin/org-import-export.md
   - Development:
       - develop/index.md
       - develop/local-dev-setup.md
@@ -107,6 +107,8 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.details
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.keys
   - def_list
   - attr_list