Enable new mkdocs-material features (#2451)

Signed-off-by: Daniel Gray <[email protected]>
privacyguides · Apr 5, 2024 · cf43545 · cf43545
1 parent cca4759
commit cf43545
Show file tree

Hide file tree

Showing 25 changed files with 599 additions and 359 deletions.
diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml
@@ -29,6 +29,7 @@ permissions:
   contents: write
   pages: write
   id-token: write
+  deployments: write
 
 jobs:
   submodule:

diff --git a/.gitignore b/.gitignore
@@ -2,10 +2,8 @@ site
 /i18n/
 /includes/*
 !/includes/*.en.*
-/static/i18n/*
-!/static/i18n/*.en.*
-/theme/overrides/*
-!/theme/overrides/*.en.*
+/static/i18n/
+/theme/overrides/*.*.*
 
 # commit social card fonts to repo
 # see: https://github.com/squidfunk/mkdocs-material/issues/6983

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/config/layouts/home.yml b/config/layouts/home.yml
@@ -24,7 +24,7 @@ definitions:
     {{ page.meta.get("title", page.title) }}
 
   - &page_description >-
-    {{ config.extra.homepage_description }}
+    {{ config.extra.privacy_guides.homepage.description }}
 
   - &og_description >-
     {{ page.meta.get("description", config.site_description) or "" }}

diff --git a/config/mkdocs-common.yml b/config/mkdocs-common.yml
@@ -28,22 +28,139 @@ site_description:
     SITE_DESCRIPTION,
     "Privacy Guides is your central privacy and security resource to protect yourself online.",
   ]
-copyright:
-  !ENV [FOOTER_COPYRIGHT, "&copy; 2019 Privacy Guides and contributors."]
-edit_uri: edit/main/docs/
+edit_uri_template: blob/main/docs/{path}?plain=1
 
 extra:
   generator: false
   context: !ENV [CONTEXT, "production"]
   deploy: !ENV DEPLOY_ID
-  homepage_description:
-    !ENV [
-      DESCRIPTION_HOMEPAGE,
-      "A socially motivated website which provides information about protecting your online data privacy and security.",
-    ]
-  translation_notice: !ENV DESCRIPTION_TRANSLATION
-  translation_notice_cta: !ENV [DESCRIPTION_TRANSLATION_CTA, "Visit Crowdin"]
-  translation_notice_language: !ENV LANG_ENGLISH
+  privacy_guides:
+    footer:
+      intro:
+        !ENV [
+          FOOTER_INTRO,
+          "Privacy Guides is a non-profit, socially motivated website that provides information for protecting your data security and privacy.",
+        ]
+      note:
+        !ENV [
+          FOOTER_NOTE,
+          "We do not make money from recommending certain products, and we do not use affiliate links.",
+        ]
+      copyright:
+        author:
+          !ENV [FOOTER_COPYRIGHT_AUTHOR, "Privacy Guides and contributors."]
+        date: !ENV [FOOTER_COPYRIGHT_DATE, "2019-2024"]
+      license:
+        - fontawesome/brands/creative-commons
+        - fontawesome/brands/creative-commons-by
+        - fontawesome/brands/creative-commons-nd
+      analytics: !ENV [FOOTER_ANALYTICS, "Anonymous statistics preferences."]
+    homepage:
+      description:
+        !ENV [
+          HOMEPAGE_DESCRIPTION,
+          "A socially motivated website which provides information about protecting your online data privacy and security.",
+        ]
+      hero:
+        header:
+          !ENV [HOMEPAGE_HEADER, "The guide to restoring your online privacy."]
+        subheader:
+          !ENV [
+            HOMEPAGE_SUBHEADER,
+            "Massive organizations are monitoring your online activities. Privacy Guides is your central privacy and security resource to protect yourself online.",
+          ]
+        buttons:
+          - name:
+              !ENV [
+                HOMEPAGE_BUTTON_GET_STARTED_NAME,
+                "Start Your Privacy Journey",
+              ]
+            title:
+              !ENV [
+                HOMEPAGE_BUTTON_GET_STARTED_TITLE,
+                "The first step of your privacy journey",
+              ]
+            link: basics/why-privacy-matters/
+            class: md-button md-button--primary
+          - name: !ENV [HOMEPAGE_BUTTON_TOOLS_NAME, "Recommended Tools"]
+            title:
+              !ENV [
+                HOMEPAGE_BUTTON_TOOLS_TITLE,
+                "Recommended privacy tools, services, and knowledge",
+              ]
+            link: tools/
+            class: md-button
+      cta:
+        - title:
+            !ENV [
+              HOMEPAGE_CTA_TITLE,
+              "We need you! Here's how to get involved:",
+            ]
+          links:
+            - icon: simple/discourse
+              name: !ENV [HOMEPAGE_CTA_FORUM_NAME, "Join the forum"]
+              link: https://discuss.privacyguides.net/
+            - icon: simple/mastodon
+              name: !ENV [HOMEPAGE_CTA_MASTODON_NAME, "Follow us on Mastodon"]
+              link: https://mastodon.neat.computer/@privacyguides
+            - icon: simple/github
+              name: !ENV [HOMEPAGE_CTA_GITHUB_NAME, "Contribute on GitHub"]
+              link: https://github.com/privacyguides/privacyguides.org
+            - icon: material/translate
+              name: !ENV [HOMEPAGE_CTA_TRANSLATE_NAME, "Help translate"]
+              link: https://crowdin.com/project/privacyguides
+            - icon: simple/matrix
+              name: !ENV [HOMEPAGE_CTA_MATRIX_NAME, "Join the Matrix chat"]
+              link: https://matrix.to/#/#privacyguides:matrix.org
+            - icon: material/information-outline
+              name: !ENV [HOMEPAGE_CTA_ABOUT_NAME, "Learn more about us"]
+              link: about/
+            - icon: material/hand-coin
+              name: !ENV [HOMEPAGE_CTA_DONATE_NAME, "Donate to Privacy Guides"]
+              link: about/donate/
+          description:
+            !ENV [
+              HOMEPAGE_CTA_DESCRIPTION,
+              "If you spot an error, think a provider should not be listed, notice a qualified provider is missing, believe a browser plugin is no longer the best choice, or uncover any other issue, please let us know.",
+            ]
+      rss:
+        - title:
+            !ENV [
+              HOMEPAGE_RSS_CHANGELOG_TITLE,
+              "Privacy Guides release changelog",
+            ]
+          link:
+            !ENV [
+              HOMEPAGE_RSS_CHANGELOG_LINK,
+              "https://discuss.privacyguides.net/c/site-development/changelog/9.rss",
+            ]
+        - title: !ENV [HOMEPAGE_RSS_BLOG_TITLE, "Privacy Guides blog feed"]
+          link:
+            !ENV [
+              HOMEPAGE_RSS_BLOG_LINK,
+              "https://blog.privacyguides.org/feed_rss_created.xml",
+            ]
+        - title:
+            !ENV [HOMEPAGE_RSS_STORIES_TITLE, "Privacy Guides Web Stories feed"]
+          link:
+            !ENV [
+              HOMEPAGE_RSS_STORIES_LINK,
+              "https://share.privacyguides.org/web-stories/feed/",
+            ]
+        - title:
+            !ENV [
+              HOMEPAGE_RSS_FORUM_TITLE,
+              "Latest Privacy Guides forum topics",
+            ]
+          link:
+            !ENV [
+              HOMEPAGE_RSS_FORUM_LINK,
+              "https://discuss.privacyguides.net/latest.rss",
+            ]
+    translation_notice:
+      notice: !ENV TRANSLATION_NOTICE
+      cta: !ENV [TRANSLATION_NOTICE_CTA, "Visit Crowdin"]
+      language: !ENV LANG_ENGLISH
   social:
     - icon: simple/mastodon
       link: https://mastodon.neat.computer/@privacyguides
@@ -95,19 +212,22 @@ extra:
       icon: https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f1f7-1f1fa.svg
   analytics:
     feedback:
-      title: Was this page helpful?
+      title: !ENV [ANALYTICS_FEEDBACK_TITLE, "Was this page helpful?"]
       ratings:
         - icon: material/emoticon-happy-outline
-          name: This page was helpful
+          name: !ENV [ANALYTICS_FEEDBACK_POSITIVE_NAME, "This page was helpful"]
           data: 1
-          note: >-
-            Thanks for your feedback!
+          note:
+            !ENV [ANALYTICS_FEEDBACK_POSITIVE_NOTE, "Thanks for your feedback!"]
         - icon: material/emoticon-sad-outline
-          name: This page could be improved
+          name:
+            !ENV [
+              ANALYTICS_FEEDBACK_NEGATIVE_NAME,
+              "This page could be improved",
+            ]
           data: 0
-          note: >-
-            Thanks for your feedback! If you want to let us know more, please leave a post on our
-            <a href="https://discuss.privacyguides.net/c/site-development/7" target="_blank" rel="noopener">forum</a>.
+          note:
+            !ENV [ANALYTICS_FEEDBACK_NEGATIVE_NOTE, "Thanks for your feedback!"]
   consent:
     title: !ENV [ANALYTICS_CONSENT_TITLE, "Contribute anonymous statistics"]
     description:
@@ -167,6 +287,7 @@ theme:
     - navigation.expand
     - navigation.path
     - navigation.indexes
+    - content.action.edit
     - content.tabs.link
     - content.tooltips
     - search.highlight
@@ -212,6 +333,10 @@ plugins:
 
 markdown_extensions:
   admonition: {}
+  material.extensions.preview:
+    sources:
+      exclude:
+        - tools.md
   pymdownx.details: {}
   pymdownx.superfences:
     custom_fences:

diff --git a/config/mkdocs-offline.yml b/config/mkdocs-offline.yml
@@ -22,11 +22,36 @@ INHERIT: mkdocs-common.yml
 
 # Disable any GitHub integrations
 repo_url: ""
+edit_uri_template: ""
 
 extra:
   # Disable language switcher
   alternate: false
   offline: true
+  privacy_guides:
+    homepage:
+      hero:
+        buttons:
+          - name:
+              !ENV [
+                HOMEPAGE_BUTTON_GET_STARTED_NAME,
+                "Start Your Privacy Journey",
+              ]
+            title:
+              !ENV [
+                HOMEPAGE_BUTTON_GET_STARTED_TITLE,
+                "The first step of your privacy journey",
+              ]
+            link: basics/why-privacy-matters.html
+            class: md-button md-button--primary
+          - name: !ENV [HOMEPAGE_BUTTON_TOOLS_NAME, "Recommended Tools"]
+            title:
+              !ENV [
+                HOMEPAGE_BUTTON_TOOLS_TITLE,
+                "Recommended privacy tools, services, and knowledge",
+              ]
+            link: tools.html
+            class: md-button
 
 theme:
   # OFFLINE ONLY: this logo needs to be set separately because the relative path is different

diff --git a/config/mkdocs.es.yml b/config/mkdocs.es.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/es"
 site_url: "https://www.privacyguides.org/es/"
 site_dir: "../site/es"
 
-edit_uri: edit/main/i18n/es/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/es/{path}?plain=1
 
 theme:
   language: es

diff --git a/config/mkdocs.fr.yml b/config/mkdocs.fr.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/fr"
 site_url: "https://www.privacyguides.org/fr/"
 site_dir: "../site/fr"
 
-edit_uri: edit/main/i18n/fr/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/fr/{path}?plain=1
 
 theme:
   language: fr

diff --git a/config/mkdocs.he.yml b/config/mkdocs.he.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/he"
 site_url: "https://www.privacyguides.org/he/"
 site_dir: "../site/he"
 
-edit_uri: edit/main/i18n/he/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/he/{path}?plain=1
 
 extra_css:
   - assets/stylesheets/extra.css?v=3.2.0

diff --git a/config/mkdocs.it.yml b/config/mkdocs.it.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/it"
 site_url: "https://www.privacyguides.org/it/"
 site_dir: "../site/it"
 
-edit_uri: edit/main/i18n/it/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/it/{path}?plain=1
 
 theme:
   language: it

diff --git a/config/mkdocs.nl.yml b/config/mkdocs.nl.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/nl"
 site_url: "https://www.privacyguides.org/nl/"
 site_dir: "../site/nl"
 
-edit_uri: edit/main/i18n/nl/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/nl/{path}?plain=1
 
 theme:
   language: nl

diff --git a/config/mkdocs.ru.yml b/config/mkdocs.ru.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/ru"
 site_url: "https://www.privacyguides.org/ru/"
 site_dir: "../site/ru"
 
-edit_uri: edit/main/docs/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/ru/{path}?plain=1
 
 extra_css:
   - assets/stylesheets/extra.css?v=3.2.0

diff --git a/config/mkdocs.zh-Hant.yml b/config/mkdocs.zh-Hant.yml
@@ -23,7 +23,7 @@ docs_dir: "../i18n/zh-Hant"
 site_url: "https://www.privacyguides.org/zh-Hant/"
 site_dir: "../site/zh-Hant"
 
-edit_uri: edit/main/i18n/zh-Hant/
+edit_uri_template: https://github.com/privacyguides/i18n/blob/main/i18n/zh-Hant/{path}?plain=1
 
 extra_css:
   - assets/stylesheets/extra.css?v=3.2.0

diff --git a/crowdin.yml b/crowdin.yml
@@ -26,18 +26,8 @@ files:
   - source: "/docs/**/*.*"
     translation: "/i18n/%two_letters_code%/**/%file_name%.%file_extension%"
     skip_untranslated_files: false
-  - source: "/theme/overrides/*.en.html"
-    translation: "/theme/overrides/%file_name%.%two_letters_code%.html"
-    translation_replace:
-      "en.": ""
-    skip_untranslated_files: false
   - source: "/includes/*.en.*"
     translation: "/includes/%file_name%.%two_letters_code%.%file_extension%"
     translation_replace:
       "en.": ""
     skip_untranslated_files: false
-  - source: "/static/i18n/*.en.*"
-    translation: "/static/i18n/%file_name%.%two_letters_code%.%file_extension%"
-    translation_replace:
-      "en.": ""
-    skip_untranslated_files: false
diff --git a/docs/about/criteria.md b/docs/about/criteria.md
@@ -2,30 +2,19 @@
 title: General Criteria
 ---
 
-<div class="admonition example" markdown>
-<p class="admonition-title">Work in Progress</p>
+Below are some general priorities we consider for all submissions to Privacy Guides. Each category will have additional requirements for inclusion.
 
-The following page is a work in progress, and does not reflect the full criteria for our recommendations at this time. Past discussion on this topic: [#24](https://github.com/privacyguides/privacyguides.org/discussions/24)
-
-</div>
-
-Below are some things that must apply to all submissions to Privacy Guides. Each category will have additional requirements for inclusion.
+- **Security**: Tools should follow security best-practices wherever applicable.
+- **Source Availability**: Open-source projects are generally preferred over equivalent proprietary alternatives.
+- **Cross-Platform Availability**: We typically prefer recommendations to be cross-platform, to avoid vendor lock-in.
+- **Active Development**: The tools that we recommend should be actively developed, unmaintained projects will be removed in most cases.
+- **Usability**: Tools should be accessible to most computer users, an overly technical background should not be required.
+- **Documentation**: Tools should have clear and extensive documentation for use.
 
 ## Financial Disclosure
 
 We do not make money from recommending certain products, we do not use affiliate links, and we do not provide special consideration to project donors.
 
-## General Guidelines
-
-We apply these priorities when considering new recommendations:
-
-- **Secure**: Tools should follow security best-practices wherever applicable.
-- **Source Availability**: Open-source projects are generally preferred over equivalent proprietary alternatives.
-- **Cross-Platform**: We typically prefer recommendations to be cross-platform, to avoid vendor lock-in.
-- **Active Development**: The tools that we recommend should be actively developed, unmaintained projects will be removed in most cases.
-- **Usability**: Tools should be accessible to most computer users, an overly technical background should not be required.
-- **Documented**: Tools should have clear and extensive documentation for use.
-
 ## Developer Self-Submissions
 
 We have these requirements in regard to developers which wish to submit their project or software for consideration.