From 7377a98fd14191134f567949e1a95f317c45db24 Mon Sep 17 00:00:00 2001 From: david-swift Date: Sat, 12 Apr 2025 21:33:30 +0200 Subject: [PATCH] Improve documentation design #3 --- sass/_article.scss | 55 +++++++++---------- sass/_docs.scss | 89 ++++++++++++++++++++++++------- sass/_general.scss | 5 +- sass/_variables.scss | 15 +++--- templates/404.html | 2 +- templates/article.html | 2 +- templates/article_list.html | 2 +- templates/base.html | 3 +- templates/documentation_page.html | 28 +++++----- templates/index.html | 2 +- templates/page.html | 2 +- templates/restricted_base.html | 5 -- templates/section.html | 2 +- templates/subproject.html | 2 +- templates/subproject_list.html | 2 +- templates/taxonomy_list.html | 2 +- templates/taxonomy_single.html | 2 +- 17 files changed, 133 insertions(+), 87 deletions(-) delete mode 100644 templates/restricted_base.html diff --git a/sass/_article.scss b/sass/_article.scss index 05ff9f1..d73f27c 100644 --- a/sass/_article.scss +++ b/sass/_article.scss @@ -74,33 +74,6 @@ margin-block-start: 2rem; } - summary, - #go-to-top, - #share, - #issue { - display: inline-block; - transition: var(--transition); - box-shadow: var(--edge-highlight); - border-radius: 999px; - background-color: var(--fg-muted-1); - padding: 0.5rem; - color: var(--fg-muted-4); - line-height: 0; - - &:hover { - background-color: var(--fg-muted-2); - color: var(--fg-muted-5); - } - - &:active { - transform: var(--active); - } - - .icon { - transition: var(--transition); - } - } - details { position: relative; box-shadow: none; @@ -246,3 +219,31 @@ mask-image: var(--icon-bug); } } + +summary, +#go-to-top, +#share, +#issue, +.toggle-label { + display: inline-block; + transition: var(--transition); + box-shadow: var(--edge-highlight); + border-radius: 999px; + background-color: var(--fg-muted-1); + padding: 0.5rem; + color: var(--fg-muted-4); + line-height: 0; + + &:hover { + background-color: var(--fg-muted-2); + color: var(--fg-muted-5); + } + + &:active { + transform: var(--active); + } + + .icon { + transition: var(--transition); + } +} diff --git a/sass/_docs.scss b/sass/_docs.scss index f2fe21c..6f48121 100644 --- a/sass/_docs.scss +++ b/sass/_docs.scss @@ -2,7 +2,7 @@ padding: 0.5em 1em; border-radius: var(--rounded-corner); min-width: 200px; - margin: 0rem 1rem 0rem 1rem; + margin: 1rem 1rem 0rem 1rem; ul { padding: 0; @@ -20,12 +20,12 @@ } a:hover { - background: var(--fg-muted-1-soft); + background: var(--fg-muted-1-transparent); transition: 0.1s; } .active { - background: var(--fg-muted-1); + background: var(--fg-muted-1-transparent); color: var(--fg-muted-5); } @@ -36,29 +36,82 @@ } #docs-container { + background-color: var(--fg-muted-1-soft); + border-right: 1px solid var(--fg-muted-1); + box-sizing: border-box; display: flex; - flex-wrap: wrap; + justify-content: flex-end; + min-width: 15em; + width: calc(50% - var(--container-width) / 2 - 6em); + border-radius: 0; + margin: 0; + overflow: auto; + scroll-behavior: smooth; + position: fixed; height: 100%; - justify-content: center; + z-index: 10; +} - #docs { - left: 1em; - margin-bottom: 1em; - } +#sidebar-toggle { + display: none; +} - article { +.toggle-label { + padding: 10px 20px; + cursor: pointer; + display: none; + position: fixed; + padding: 0.5em; + margin: 1rem; + z-index: 100; + + .icon { + -webkit-mask-image: var(--icon-sidebar); + mask-image: var(--icon-sidebar); margin-left: auto; - margin-right: auto; - max-width: var(--container-width); - min-width: var(--min-container-width); } } -#toc-hidden { - visibility: hidden; - height: 0px; +.toggle-overlay { + position: fixed; + inset: 0; + z-index: 5; + display: none } -.expand-main { - width: 100%; +@media only screen and (max-width: calc(720px + 12em + 30em)) { + .toggle-label { + display: block; + left: 0; + transition: left 0.5s; + } + + .toggle-overlay { + background-color: rgba(0, 0, 0, 0); + transition: background-color 0.5s; + display: block; + pointer-events: none; + } + + #docs-container { + left: -15em; + transition: left 0.5s; + box-shadow: var(--shadow); + } + + #sidebar-toggle:checked ~ #docs-container { + left: 0; + transition: left 0.5s; + } + + #sidebar-toggle:checked ~ .toggle-label { + left: 15em; + transition: left 0.5s; + } + + #sidebar-toggle:checked ~ .toggle-overlay { + background-color: rgba(0, 0, 0, 0.5); + transition: background-color 0.5s; + pointer-events: auto; + } } diff --git a/sass/_general.scss b/sass/_general.scss index 7f15158..68aa4ab 100644 --- a/sass/_general.scss +++ b/sass/_general.scss @@ -72,10 +72,7 @@ body { main { margin: 4.25rem auto 4rem; - max-width: var(--max-container-width) -} - -.restricted-width { + max-width: var(--max-container-width); width: min(var(--container-width), 90%); } diff --git a/sass/_variables.scss b/sass/_variables.scss index 6525626..f1ea84d 100644 --- a/sass/_variables.scss +++ b/sass/_variables.scss @@ -21,9 +21,10 @@ --bg-overlay: linear-gradient(rgb(0 0 0 / 0.9), rgb(0 0 0 / 0.9)); --fg-color: rgb(255 255 255); --fg-contrast: rgb(0 0 0 / 0.8); - --fg-muted-1-soft: rgb(255 255 255 / 0.03); - --fg-muted-1: rgb(255 255 255 / 0.05); - --fg-muted-2: rgb(255 255 255 / 0.1); + --fg-muted-1-soft: #252525; + --fg-muted-1-transparent: rgb(255 255 255 / 0.05); + --fg-muted-1: #292929; + --fg-muted-2: #353535; --fg-muted-3: rgb(255 255 255 / 0.2); --fg-muted-4: rgb(255 255 255 / 0.5); --fg-muted-5: rgb(255 255 255 / 0.6); @@ -46,9 +47,10 @@ --fg-color: rgb(0 0 0 / 0.8); --fg-contrast: rgb(255 255 255); --fg-contrast-soft: rgb(255 255 255); - --fg-muted-1-soft: var(--fg-muted-1); - --fg-muted-1: rgb(0 0 0 / 0.05); - --fg-muted-2: rgb(0 0 0 / 0.1); + --fg-muted-1-soft: #EDEDED; + --fg-muted-1-transparent: rgb(0 0 0 / 0.05); + --fg-muted-1: #E9E9E9; + --fg-muted-2: #DCDCDC; --fg-muted-3: rgb(0 0 0 / 0.2); --fg-muted-4: rgb(0 0 0 / 0.5); --fg-muted-5: rgb(0 0 0 / 0.6); @@ -192,6 +194,7 @@ --icon-poop: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='M8.963 1.514A4 4 0 0 1 5 5H4c-1.108 0-2 .892-2 2s.892 2 2 2H3c-1.662 0-3 1.338-3 3s1.338 3 3 3h10c1.662 0 3-1.338 3-3s-1.338-3-3-3h-1c1.108 0 2-.892 2-2s-.892-2-2-2h-1a4 4 0 0 0-2.037-3.486'/%3E%3C/svg%3E"); --icon-previous: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='m9.293 13.707-5-5a1 1 0 0 1 0-1.414l5-5a1 1 0 1 1 1.414 1.414L6.414 8l4.293 4.293a1 1 0 1 1-1.414 1.414m0 0'/%3E%3C/svg%3E"); --icon-right: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='m5.707 1.293 6 6a1 1 0 0 1 0 1.414l-6 6a1 1 0 1 1-1.414-1.414L9.586 8 4.293 2.707a1 1 0 1 1 1.414-1.414m0 0'/%3E%3C/svg%3E"); + --icon-sidebar: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='M2 3h12c.554 0 1-.446 1-1s-.446-1-1-1H2c-.554 0-1 .446-1 1s.446 1 1 1zm0 6h12c.554 0 1-.446 1-1s-.446-1-1-1H2c-.554 0-1 .446-1 1s.446 1 1 1zm0 6h12c.554 0 1-.446 1-1s-.446-1-1-1H2c-.554 0-1 .446-1 1s.446 1 1 1z'/%3E%3C/svg%3E"); --icon-share: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='M8 1a1 1 0 0 0-.5.135 1 1 0 0 0-.207.158l-3 3a1 1 0 0 0 0 1.414 1 1 0 0 0 1.414 0L7 4.414V10a1 1 0 0 0 1 1 1 1 0 0 0 1-1V4.414l1.293 1.293a1 1 0 0 0 1.414 0 1 1 0 0 0 0-1.414L8.738 1.326 8.7 1.287a1 1 0 0 0-.195-.15l-.008-.004a1 1 0 0 0-.236-.098h-.004A1 1 0 0 0 8 1M4 7c-1.645 0-3 1.355-3 3v2c0 1.645 1.355 3 3 3h8c1.645 0 3-1.355 3-3v-2c0-1.645-1.355-3-3-3a1 1 0 0 0 0 2c.564 0 1 .436 1 1v2c0 .564-.436 1-1 1H4c-.564 0-1-.436-1-1v-2c0-.564.436-1 1-1a1 1 0 0 0 0-2'/%3E%3C/svg%3E"); --icon-star: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='M8 0a1 1 0 0 0-.95.684l-1.448 4.34-4.59-.016C.032 5.004-.371 6.266.43 6.828l3.625 2.555-1.5 4.285c-.317.902.687 1.691 1.492 1.172l4.004-2.594 3.894 2.586c.801.531 1.817-.258 1.5-1.16l-1.504-4.29 3.645-2.577c.789-.563.394-1.809-.574-1.813l-4.66-.015L8.949.69A1 1 0 0 0 8 0m0 0'/%3E%3C/svg%3E"); --icon-theme-dark: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath d='M.918 8.004a7.072 7.072 0 0 0 14.102.793 1.01 1.01 0 0 0-.457-.957 1 1 0 0 0-1.063-.004 3.9 3.9 0 0 1-2.031.578 3.89 3.89 0 0 1-3.883-3.883c0-.715.203-1.422.578-2.031a1 1 0 0 0-.004-1.062c-.207-.32-.578-.5-.957-.458A7.07 7.07 0 0 0 .918 8.004M5.586 4.53a5.877 5.877 0 0 0 8.965 5.004l-1.52-.96a5.09 5.09 0 0 1-5.035 4.507 5.09 5.09 0 0 1-5.078-5.078 5.09 5.09 0 0 1 4.508-5.035l-.961-1.52a5.9 5.9 0 0 0-.88 3.082m0 0'/%3E%3C/svg%3E"); diff --git a/templates/404.html b/templates/404.html index 964d2bd..822c669 100644 --- a/templates/404.html +++ b/templates/404.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set rel_attributes = macros_rel_attributes::rel_attributes() | trim -%} diff --git a/templates/article.html b/templates/article.html index 19806c1..6c8d524 100644 --- a/templates/article.html +++ b/templates/article.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set date_format = macros_translate::translate(key="date_format", default="%B %d, %Y", language_strings=language_strings) -%} diff --git a/templates/article_list.html b/templates/article_list.html index 559b707..496dc5f 100644 --- a/templates/article_list.html +++ b/templates/article_list.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set date_format = macros_translate::translate(key="date_format", default="%B %d, %Y", language_strings=language_strings) -%} diff --git a/templates/base.html b/templates/base.html index 132ff10..2584b31 100644 --- a/templates/base.html +++ b/templates/base.html @@ -12,10 +12,11 @@ {% include "partials/head.html" %} {% block body %} + {% block aside %}{% endblock aside %} {%- if config.extra.nav.links %} {% include "partials/nav.html" %} {%- endif %} -
+
{% block custom %}{% endblock custom %} {% block content %}{% endblock content %} {% include "partials/extra_features.html" %} diff --git a/templates/documentation_page.html b/templates/documentation_page.html index bea4b00..47a4ec4 100644 --- a/templates/documentation_page.html +++ b/templates/documentation_page.html @@ -1,8 +1,14 @@ {% extends "base.html" %} -{% block classes %} -expand-main -{% endblock classes %} +{% block aside %} + {%- set section = get_section(path=page.ancestors | last) -%} + + + + +{% endblock aside %} {% block content %} {%- set rel_attributes = macros_rel_attributes::rel_attributes() | trim -%} @@ -13,19 +19,9 @@ expand-main {%- set list_element = "ul" -%} {%- endif -%} -{%- set section = get_section(path=page.ancestors | last) -%} - -
- {% include "partials/docs_toc.html" %} - -
- {% include "partials/article_content.html" %} -
- -
- {% include "partials/docs_toc.html" %} -
-
+
+ {% include "partials/article_content.html" %} +
{%- if page.extra.comments.id -%} {%- include "partials/comments.html" -%} diff --git a/templates/index.html b/templates/index.html index 1e659c4..575141f 100644 --- a/templates/index.html +++ b/templates/index.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {{ section.content | safe }} diff --git a/templates/page.html b/templates/page.html index 98dcd59..942597f 100644 --- a/templates/page.html +++ b/templates/page.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %}

{{ page.title }}

diff --git a/templates/restricted_base.html b/templates/restricted_base.html deleted file mode 100644 index 27b995d..0000000 --- a/templates/restricted_base.html +++ /dev/null @@ -1,5 +0,0 @@ -{% extends "base.html" %} - -{% block classes %} -restricted-width -{% endblock classes %} diff --git a/templates/section.html b/templates/section.html index 101f2d1..3ba4d84 100644 --- a/templates/section.html +++ b/templates/section.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %}

{{ section.title }}

diff --git a/templates/subproject.html b/templates/subproject.html index cc0f3a4..9cc765d 100644 --- a/templates/subproject.html +++ b/templates/subproject.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set rel_attributes = macros_rel_attributes::rel_attributes() | trim -%} diff --git a/templates/subproject_list.html b/templates/subproject_list.html index 67920e3..e09cf38 100644 --- a/templates/subproject_list.html +++ b/templates/subproject_list.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} diff --git a/templates/taxonomy_list.html b/templates/taxonomy_list.html index 0409ca2..257bf8f 100644 --- a/templates/taxonomy_list.html +++ b/templates/taxonomy_list.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set number_of_tags = terms | length -%} diff --git a/templates/taxonomy_single.html b/templates/taxonomy_single.html index 41217ae..8eb9ff0 100644 --- a/templates/taxonomy_single.html +++ b/templates/taxonomy_single.html @@ -1,4 +1,4 @@ -{% extends "restricted_base.html" %} +{% extends "base.html" %} {% block content %} {%- set date_format = macros_translate::translate(key="date_format", default="%B %d, %Y", language_strings=language_strings) -%}