From 0cbc2797733bb9732a9892b7ccd6345bc06bcb32 Mon Sep 17 00:00:00 2001 From: Emma Segal-Grossman Date: Tue, 19 Nov 2024 00:43:22 -0500 Subject: [PATCH] [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 --- frontend/docs/docs/develop/docs.md | 50 +++++++++++++------ .../docs/docs/overrides/partials/actions.html | 49 ++++++++++++++++++ .../integrations/analytics/custom.html | 2 + frontend/docs/mkdocs.yml | 50 ++++++++++--------- 4 files changed, 111 insertions(+), 40 deletions(-) create mode 100644 frontend/docs/docs/overrides/partials/actions.html create mode 100644 frontend/docs/docs/overrides/partials/integrations/analytics/custom.html diff --git a/frontend/docs/docs/develop/docs.md b/frontend/docs/docs/develop/docs.md index 6ea02747..8c23247f 100644 --- 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" -In the project root directory run `mkdocs serve` to run a local version of the documentation site. + ```sh + pip install mkdocs-material + ``` -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) + Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site. + +=== "pipx" + + ```sh + pipx install mkdocs-material --include-deps + ``` + + Then, in `frontend/docs` run `mkdocs serve` to run a local version of the documentation site. + +=== "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 new file mode 100644 index 00000000..bd3b62ce --- /dev/null +++ b/frontend/docs/docs/overrides/partials/actions.html @@ -0,0 +1,49 @@ + + + + + +{% if page.edit_url %} + + +{% if "content.action.edit" in features %} + + {% set icon = config.theme.icon.edit or "material/file-edit-outline" %} + {% include ".icons/" ~ icon ~ ".svg" %} + +{% endif %} + + +{% if "content.action.view" in features %} +{% if "/blob/" in page.edit_url %} +{% set part = "blob" %} +{% else %} +{% set part = "edit" %} +{% endif %} + + {% set icon = config.theme.icon.view or "material/file-eye-outline" %} + {% include ".icons/" ~ icon ~ ".svg" %} + +{% endif %} +{% endif %} diff --git a/frontend/docs/docs/overrides/partials/integrations/analytics/custom.html b/frontend/docs/docs/overrides/partials/integrations/analytics/custom.html new file mode 100644 index 00000000..7a5d2a2e --- /dev/null +++ b/frontend/docs/docs/overrides/partials/integrations/analytics/custom.html @@ -0,0 +1,2 @@ + + diff --git a/frontend/docs/mkdocs.yml b/frontend/docs/mkdocs.yml index 44d938e8..71a326e7 100644 --- 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