Insider features (#1113)

* add dark/light theme
* cookies consent
* adjust colours
* feedback widget
* add a specific insider config
* add grid on index
* clean extensions and plugin files (was mixed)
* add socials

Signed-off-by: Nicolas MASSART <nicolas.massart@consensys.net>

.circleci/config.yml

@@ -72,8 +72,7 @@ jobs:
             python3 -m venv venv
             . venv/bin/activate
             pip install --upgrade pip
-            pip install -q -r CI/requirements-mkdocs-material.txt
+            pip install -q -r CI/requirements-mkdocs-material.txt -r CI/requirements.txt
-            pip install -q -r CI/requirements.txt
       - save_cache:
           paths:
             - ./venv

.gitignore

@@ -6,3 +6,5 @@ node_modules/
 .circleci/process.yml
 .DS_Store
 *.log
+.lh
+.run

.lh/.lhignore

@@ -1,6 +0,0 @@
-# list file to not track by the local-history extension. comment line starts with a '#' character
-# each line describe a regular expression pattern (search for "Javascript regex")
-# it will relate to the workspace directory root. for example:
-# ".*\.txt" ignores any file with "txt" extension
-# "/test/.*" ignores all the files under the "test" directory
-# ".*/test/.*" ignores all the files under any "test" directory (even under sub-folders)

.readthedocs.yaml

@@ -16,5 +16,5 @@ python:
     - requirements: CI/requirements.txt
 
 mkdocs:
-  configuration: mkdocs.yml
+  configuration: mkdocs-insider.yml
-  fail_on_warning: false
+  fail_on_warning: true

CI/requirements.txt

@@ -1,10 +1,8 @@
-Markdown==3.4.1
 markdown-fenced-code-tabs==1.0.5
-markdown-include==0.6.0
+markdown-include==0.7.0
 mkdocs-markdownextradata-plugin==0.2.5
 mkdocs-exclude==1.0.2
 mkdocs-redirects==1.0.4
 mkdocs-git-revision-date-localized-plugin==1.1.0
 mkdocs-minify-plugin==0.5.0
-plantuml-markdown==3.5.3
+plantuml-markdown==3.6.2
-

custom_theme/assets/stylesheets/custom_theme.css

@@ -1,79 +1,106 @@
-.feedback{
+/*Light and dark scheme dependent colour variables*/
+
+:root, [data-md-color-scheme=default] {
+  --mdx-version-notice-bg-color: #ff8721;
+  --mdx-custom-footer-bg-color: #00bda4;
+  --mdx-custom-footer-fg-color: #000;
+  --mdx-admonition-critical-border-color: rgb(220, 0, 0);
+  --mdx-admonition-critical-bg-color: rgb(250, 150, 150);
+  --mdx-admonition-critical-title-color: #FFF;
+}
+:root, [data-md-color-scheme=slate] {
+  --mdx-version-notice-bg-color: #d26000;
+  --mdx-custom-footer-bg-color: #008c7b;
+  --mdx-custom-footer-fg-color: #fff;
+  --mdx-admonition-critical-border-color: rgb(220, 0, 0);
+  --mdx-admonition-critical-bg-color: rgb(160, 0, 0);
+  --mdx-admonition-critical-title-color: #FFF;
+}
+
+/*Footer feedback banner*/
+.custom-footer{
   padding: 1em;
   text-align: center;
-  background-color: lightseagreen;
+  color: var(--mdx-custom-footer-fg-color);
+  background-color: var(--mdx-custom-footer-bg-color);
 }
-.feedback a {
+.custom-footer a {
-  color: white !important;
+  color: var(--mdx-custom-footer-fg-color) !important;
 }
+
+/*Navigation customisation*/
 .md-nav--secondary .md-nav__item .md-nav__item a.md-nav__link {
   font-weight: normal;
   font-size: inherit;
 }
 .md-nav--secondary a.md-nav__link {
     font-weight: bolder;
-    <!--font-size: larger;-->
 }
 
+/*Readthedocs version box customisation*/
 .rst-versions {
-  border-color: lightseagreen !important;
+  border-color: var(--md-accent-fg-color) !important;
   border-style: solid !important;
   font-size: large;
 }
 
 .rst-versions .rst-current-version {
-  background-color: #475c64 !important;
+  background-color: var(--md-default-bg-color) !important;
 }
 
+/*Custom font for header permalinks*/
 .headerlink {
-  font-family: "Font Awesome 5 Free";
+  font-family: "Font Awesome 5 Free", sans-serif;
   font-weight: 900;
   font-size: small;
 }
 
+
+/*Latest doc version warning banner*/
 .latest-warning {
   display: none;
   padding: 1em;
-  background-color: orange;
+  background-color: var(--mdx-version-notice-bg-color);
-  color: black;
+  color: var(--md-typeset-color);
   font-size: 1.5em;
   text-align: center;
   width: inherit;
 }
 
+/*Page footer*/
 .md-footer-copyright {
     max-width: 100% !important;
 }
 
-.md-footer a[href^="http"]:after,
+/*External links arrow symbol*/
+.md-footer a[href^="http"]:not(.md-social__link):after,
 .feedback a[href^="http"]:after,
 .md-content a[href^="http"]:not(.md-content__icon):not(.md-content__button):after {
-  font-family: "Font Awesome 5 Free";
+  font-family: "Font Awesome 5 Free", sans-serif;
   font-weight: 900;
   font-size: small;
   content: " \f360";
 }
 
+/*Logo auto sizing*/
 #header-logo{
   width: auto;
 }
 
+/*Page last change date in italic*/
 .md-source-date {
   font-style: italic;
 }
 
-.md-sidebar__scrollwrap{
+/*Critical admonition design*/
-  scroll-snap-type: none !important;
-}
-
 :root {
   --md-admonition-icon--critical: url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M13 14h-2V9h2m0 9h-2v-2h2M1 21h22L12 2 1 21z'/></svg>")
 }
 
 .md-typeset .admonition.critical,
 .md-typeset details.critical {
-  border-color: rgb(222, 0, 0);
+  border-color: var(--mdx-admonition-critical-border-color);
-  background-color: #ffaaaa;
+  background-color: var(--mdx-admonition-critical-bg-color);
 }
 
 .md-typeset .admonition.critical strong{
@@ -82,13 +109,23 @@
 
 .md-typeset .critical > .admonition-title,
 .md-typeset .critical > summary {
-  color: white;
+  color: var(--mdx-admonition-critical-title-color);
-  background-color: rgb(222, 0, 0);
+  background-color: var(--mdx-admonition-critical-border-color);
-  border-color: rgb(222, 0, 0);
+  border-color: var(--mdx-admonition-critical-border-color);
 }
 .md-typeset .critical > .admonition-title::before,
 .md-typeset .critical > summary::before {
-  background-color: white;
+  background-color: var(--mdx-admonition-critical-title-color);
   -webkit-mask-image: var(--md-admonition-icon--critical);
   mask-image: var(--md-admonition-icon--critical);
 }
+
+/*Cookie consent*/
+.md-consent__overlay {
+  display: none;
+}
+
+.md-consent__inner {
+  background-color: var(--md-default-fg-color);
+  color: var(--md-default-bg-color);
+}

custom_theme/partials/content.html

@@ -16,3 +16,7 @@
   <h1>{{ page.title | d(config.site_name, true)}}</h1>
 {% endif %}
 {{ page.content }}
+
+{% if config.extra.is_insider %}
+  {% include "partials/feedback.html" %}
+{% endif %}

custom_theme/partials/footer.html

@@ -1,76 +1,55 @@
-<!--
-  Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
-  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.
--->
-
-{% import "partials/language.html" as lang with context %}
-
-<div class="feedback md-typeset">
-  Questions or feedback? You can discuss <a href="{{config.extra.support.issues}}">issues</a> and obtain free support on <a href="{{config.extra.support.chat}}">{{config.site_name}} chat channel</a>.
-  <br/>
-  For <a href="{{config.extra.support.website}}">Hyperledger Besu</a> community support, contact the mailing list <a href="mailto:{{config.extra.support.email}}">{{config.extra.support.email}}</a>
-</div>
-
-<!-- Application footer -->
 <footer class="md-footer">
   {% if page.previous_page or page.next_page %}
-    {% if page.meta and page.meta.hide %}
+  {% if page.meta and page.meta.hide %}
-      {% set hidden = "hidden" if "footer" in page.meta.hide %}
+  {% set hidden = "hidden" if "footer" in page.meta.hide %}
-    {% endif %}
+  {% endif %}
-    <nav class="md-footer__inner md-grid" aria-label="{{ lang.t('footer.title') }}" {{ hidden }}>
+  <nav class="md-footer__inner md-grid" aria-label="{{ lang.t('footer.title') }}" {{ hidden }}>
-      {% if page.previous_page %}
+    {% if page.previous_page %}
-        {% set direction = lang.t("footer.previous") %}
+    {% set direction = lang.t("footer.previous") %}
-        <a href="{{ page.previous_page.url | url }}" class="md-footer__link md-footer__link--prev" aria-label="{{ direction }}: {{ page.previous_page.title | e }}" rel="prev">
+    <a href="{{ page.previous_page.url | url }}" class="md-footer__link md-footer__link--prev" aria-label="{{ direction }}: {{ page.previous_page.title | e }}" rel="prev">
-          <div class="md-footer__button md-icon">
+      <div class="md-footer__button md-icon">
-            {% include ".icons/material/arrow-left.svg" %}
+        {% include ".icons/material/arrow-left.svg" %}
-          </div>
+      </div>
-          <div class="md-footer__title">
+      <div class="md-footer__title">
-            <div class="md-ellipsis">
+        <div class="md-ellipsis">
               <span class="md-footer__direction">
                 {{ direction }}
               </span>
-              {{ page.previous_page.title }}
+          {{ page.previous_page.title }}
-            </div>
+        </div>
-          </div>
+      </div>
-        </a>
+    </a>
-      {% endif %}
+    {% endif %}
-      {% if page.next_page %}
+    {% if page.next_page %}
-        {% set direction = lang.t("footer.next") %}
+    {% set direction = lang.t("footer.next") %}
-        <a href="{{ page.next_page.url | url }}" class="md-footer__link md-footer__link--next" aria-label="{{ direction }}: {{ page.next_page.title | e }}" rel="next">
+    <a href="{{ page.next_page.url | url }}" class="md-footer__link md-footer__link--next" aria-label="{{ direction }}: {{ page.next_page.title | e }}" rel="next">
-          <div class="md-footer__title">
+      <div class="md-footer__title">
-            <div class="md-ellipsis">
+        <div class="md-ellipsis">
               <span class="md-footer__direction">
                 {{ direction }}
               </span>
-              {{ page.next_page.title }}
+          {{ page.next_page.title }}
-            </div>
+        </div>
-          </div>
+      </div>
-          <div class="md-footer__button md-icon">
+      <div class="md-footer__button md-icon">
-            {% include ".icons/material/arrow-right.svg" %}
+        {% include ".icons/material/arrow-right.svg" %}
-          </div>
+      </div>
-        </a>
+    </a>
-      {% endif %}
+    {% endif %}
-    </nav>
+  </nav>
   {% endif %}
+
+  <div class="custom-footer md-typeset">
+    Questions or feedback? You can discuss <a href="{{config.extra.support.issues}}">issues</a> and obtain free support on <a href="{{config.extra.support.chat}}">{{config.site_name}} chat channel</a>.
+    <br/>
+    For <a href="{{config.extra.support.website}}">Hyperledger Besu</a> community support, contact the mailing list <a href="mailto:{{config.extra.support.email}}">{{config.extra.support.email}}</a>
+  </div>
+
   <div class="md-footer-meta md-typeset">
     <div class="md-footer-meta__inner md-grid">
       {% include "partials/copyright.html" %}
       {% if config.extra.social %}
-        {% include "partials/social.html" %}
+      {% include "partials/social.html" %}
       {% endif %}
     </div>
   </div>

docs/index.md

@@ -7,6 +7,26 @@ description: Besu is an open-source Ethereum client developed under the Apache 2
 
 # Besu Ethereum client
 
+<div class="grid cards" markdown>
+
+* :material-book-open-variant: __Public networks__
+
+    ---
+
+    You can run Besu as an execution client on Ethereum Mainnet and Ethereum public testnets, such as Goerli and Sepolia.
+
+    [:octicons-arrow-right-24: Getting started](HowTo/Get-Started/System-Requirements/System-Requirements-Public.md)
+
+* :material-book-lock-outline: __Private networks__
+
+    ---
+
+    You can create or join a network not connected to Mainnet or a public testnet. Use private networks to develop enterprise applications requiring secure, high-performance transaction processing.
+
+    [:octicons-arrow-right-24: Getting started](HowTo/Get-Started/System-Requirements/System-Requirements-Private.md)
+
+</div>
+
 ## What is Hyperledger Besu?
 
 Hyperledger Besu is an open-source Ethereum client developed under the Apache 2.0 license and written in Java.

mkdocs-insider.yml

@@ -0,0 +1,27 @@
+---
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+# an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the License.
+INHERIT: mkdocs.yml # DO NOT MODIFY THIS LINE
+
+plugins:
+  meta:
+    meta_file: '**/.meta.yml'
+
+extra:
+  # indicates to the templating system that the current build uses insider
+  # used to display insider only features in templates and prevent build fail on the normal version.
+  is_insider: true
+
+# The following has to be in this file and mkdocs.yml file because
+# readthedocs.org is overriding it wrong if not in the initial config file but in a child file.
+# The side effect is that it also allows us to have different scripts and CSS for insider theme
+extra_css:
+  - assets/stylesheets/custom_theme.css
+extra_javascript:
+  - assets/javascripts/custom_theme.js

mkdocs.extensions.yml

@@ -30,7 +30,9 @@ markdown_extensions:
       smart_enable: all
   - pymdownx.keys
   - pymdownx.details
-  - pymdownx.emoji
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.magiclink
   - pymdownx.mark
   - pymdownx.smartsymbols
@@ -40,21 +42,4 @@ markdown_extensions:
   - meta
   - smarty
   - attr_list
-
+  - md_in_html
-# Extensions list requires the object list format without dashes and with {} for empty entries.
-plugins:
-  search:
-      lang: 'en'
-      separator: '[\s\-\.\_]+'
-  markdownextradata: {}
-  exclude:
-    glob:
-      - global/*
-  git-revision-date-localized:
-    locale: en
-  tags: {}
-  minify:
-    minify_html: true
-    minify_js: true
-    htmlmin_opts:
-      remove_comments: true

mkdocs.extra.yml

@@ -28,9 +28,45 @@ extra:
     issues: https://github.com/hyperledger/besu/issues
     doc_issues: https://github.com/hyperledger/besu-docs/issues/new/choose
   analytics:
-    provider: tag_manager
+    provider: google
-    site_verification:
+    property: 'G-23GVTD3LEQ'
-      - 'sGzYdFR_AYDRtsC-SNxMRwjellnfTgs5ZA0q7GIM5j0'
+    feedback:
-    tag_manager: 'GTM-TS3WLJM'
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >-
+            Thanks for your feedback! Help us improve this page by
+            adding a comment in <a href="https://github.com/hyperledger/besu-docs/discussions/new?category=feedback&title=[Feedback]%20{title}&body=*%20Page:%20{title}%0A*%20URL:%20`{url}`" target=_blank>Besu discussion</a>.
+            Besu discussion requires to login on Github.
   logo_regular: logo.svg
   logo_reversed: logo-reversed.svg
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for.
+      <br/>
+      With your consent, you're helping us to make our documentation better.
+      <br/>
+      After this initial choice, you can manage your preferences by clicking on "Change cookie settings" in the page footer.
+    actions:
+      - accept
+      - reject
+      - manage
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/hyperledger/besu/
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/hyperledger
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/hyperledger/besu/tags
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/HyperledgerBesu

mkdocs.plugins.yml

@@ -9,38 +9,6 @@
 # specific language governing permissions and limitations under the License.
 INHERIT: mkdocs.navigation.yml # DO NOT MODIFY THIS LINE
 
-# Extensions list requires the dashed list format
-markdown_extensions:
-  - toc:
-      permalink: 
-      toc_depth: 3
-  - codehilite
-  - pymdownx.superfences
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.snippets:
-      base_path: docs
-      check_paths: true
-  - admonition
-  - footnotes
-  - def_list
-  - abbr
-  - pymdownx.arithmatex
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.keys
-  - pymdownx.details
-  - pymdownx.emoji
-  - pymdownx.magiclink
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-  - meta
-  - smarty
-  - attr_list
-
 # Extensions list requires the object list format without dashes and with {} for empty entries.
 plugins:
   search:
@@ -52,7 +20,6 @@ plugins:
       - global/*
   git-revision-date-localized:
     locale: en
-  tags: {}
   minify:
     minify_html: true
     minify_js: true

mkdocs.theme.yml

@@ -13,8 +13,32 @@ theme:
   name: material
   custom_dir: custom_theme
   palette:
-    primary: blue-grey
+    # Palette toggle for automatic mode
-    accent: teal
+    - media: "(prefers-color-scheme)"
+      primary: blue-grey
+      accent: teal
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      primary: blue-grey
+      accent: teal
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: blue-grey
+      accent: teal
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+
   font:
     text: Roboto
     code: Roboto Mono

mkdocs.yml

@@ -18,6 +18,7 @@ copyright: >-
   Hyperledger Besu and its documentation are licensed under Apache 2.0 license /
   This <a href="https://readthedocs.org/">Readthedocs.org</a> documentation is maintained with love
   by <a href="https://wiki.hyperledger.org/display/besu">Hyperledger Besu community</a>.
+  <a href="#__consent">Change cookie settings</a>
 
 # Doc Repository
 repo_name: hyperledger/besu-docs