[PATCH] Documentation: add logo to site header
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..192633b 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum OS documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +} -- 2.51.2
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo. [title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20... Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 6 ++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..192633b 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum OS documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..36a4017 --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,6 @@ +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +} -- 2.51.2
Valentin Gagarin <valentin@gagarin.work> writes:
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo.
[title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20...
Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 6 ++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html
diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..192633b 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum OS documentation
No "OS" in the name. (This might change in the future but should be an atomic change all at once when it happens.)
+logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..36a4017 --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,6 @@ +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %}
New files need copyright headers (and it's strongly encouraged for changes that aren't completely trivial to existing files). Otherwise release/checks/reuse.nix fails. In this case I'd take the copyright text from Just the Docs' license since that's what their license says must be preserved.
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +} -- 2.51.2
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo. [title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20... Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 9 +++++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..dbc4f7a 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..76c1b2a --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: 2016 Patrick Marsceill +# SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +} -- 2.51.2
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo. [title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20... Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 11 +++++++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..dbc4f7a 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..0b36987 --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,11 @@ +{% comment %} +SPDX-License-Identifier: MIT +SPDX-FileCopyrightText: 2016 Patrick Marsceill +SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> +{% endcomment %} +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +} -- 2.51.2
Valentin Gagarin <valentin@gagarin.work> writes:
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo.
[title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20...
Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 11 +++++++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html
diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..dbc4f7a 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..0b36987 --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,11 @@ +{% comment %} +SPDX-License-Identifier: MIT +SPDX-FileCopyrightText: 2016 Patrick Marsceill +SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> +{% endcomment %} +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) {
Took me a while to understand what was significant about 50rem here. We have access to the same SCSS mixins just-the-docs itself uses, so we could use them rather than hardcoding a magic number that might get out of sync: @include mq(md) { I also noticed that if I hover over the .site-title in a viewport wider than 50rem, its background becomes opaque and reveals that it's overflowing the sidebar. Really this is reinforcing to me that we need a version of the logo that includes the name. We need that in other contexts too, and here it would avoid the need to make changes to Just The Docs. Up to you whether it's better to wait for that or to do it this way in the meantime. I think it would also be fine if just the homepage of the documentation included the logo in its content.
+ .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } +}
Alyssa Ross <hi@alyssa.is> writes:
Valentin Gagarin <valentin@gagarin.work> writes:
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the [title template] to show both the title text and the logo.
[title template]: https://github.com/just-the-docs/just-the-docs/blob/f43d7cfc4b1e18a97e6d6d20...
Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 11 +++++++++++ Documentation/_sass/custom/custom.scss | 13 +++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 Documentation/_includes/title.html
diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..dbc4f7a 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..0b36987 --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,11 @@ +{% comment %} +SPDX-License-Identifier: MIT +SPDX-FileCopyrightText: 2016 Patrick Marsceill +SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> +{% endcomment %} +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..75e3f16 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -20,3 +20,16 @@ margin-left: 2ch; } } + +.site-logo { + width: 3rem; +} + +@media (min-width: 50rem) {
Took me a while to understand what was significant about 50rem here. We have access to the same SCSS mixins just-the-docs itself uses, so we could use them rather than hardcoding a magic number that might get out of sync:
@include mq(md) {
I also noticed that if I hover over the .site-title in a viewport wider than 50rem, its background becomes opaque and reveals that it's overflowing the sidebar.
Ignore this part. After re-applying the patch and restarting Jekyll I can't get it to happen again…
Also spell out the title. The stylesheet adjustment makes the logo align properly with the longer title text for different display widths. Override the title template to show both the title text and the logo. Signed-off-by: Valentin Gagarin <valentin@gagarin.work> --- Documentation/_config.yml | 3 ++- Documentation/_includes/title.html | 13 +++++++++++++ Documentation/_sass/custom/custom.scss | 23 ++++++++++++++++++++++- 3 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 Documentation/_includes/title.html diff --git a/Documentation/_config.yml b/Documentation/_config.yml index 90018ba..dbc4f7a 100644 --- a/Documentation/_config.yml +++ b/Documentation/_config.yml @@ -1,7 +1,8 @@ # SPDX-License-Identifier: CC0-1.0 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> --- -title: Spectrum Docs +title: Spectrum documentation +logo: "https://spectrum-os.org/logo/logo_html.svg" theme: just-the-docs aux_links: Home: diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html new file mode 100644 index 0000000..90ef71b --- /dev/null +++ b/Documentation/_includes/title.html @@ -0,0 +1,13 @@ +{% comment %} +SPDX-License-Identifier: MIT +SPDX-FileCopyrightText: 2016 Patrick Marsceill +SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> + +Override of: https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/title.... +{% endcomment %} +{% if site.logo %} + <div class="site-logo" role="img" aria-label="{{ site.title }}"></div> +{% endif %} +{% if site.title %} + {{ site.title }} +{% endif %} diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..48b1d41 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -1,5 +1,6 @@ -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> // SPDX-License-Identifier: MIT +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work> .main-content { // Just the Docs puts titles next to definitions, rather than on @@ -20,3 +21,23 @@ margin-left: 2ch; } } + +// Make the logo and title fit the site header. +.site-header { + .site-logo { + width: 3rem; + } + + // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above. + // Use the upstream `mq` media query mixin to target that breakpoint. + // https://just-the-docs.com/docs/utilities/responsive-modifiers/ + // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mi... + @include mq(md) { + .site-logo { + width: 5.5rem; + } + .site-title { + font-size: 1.25rem !important; + } + } +} -- 2.51.2
Valentin Gagarin <valentin@gagarin.work> writes:
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss index fd5a676..48b1d41 100644 --- a/Documentation/_sass/custom/custom.scss +++ b/Documentation/_sass/custom/custom.scss @@ -1,5 +1,6 @@ -// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> // SPDX-License-Identifier: MIT +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
We should pick (and document) a preferred order! I don't think we're consistent at the moment. On one hand, lexicographic ordering is nice, but on the other, license is probably more important to see first than copyright holders are.
.main-content { // Just the Docs puts titles next to definitions, rather than on @@ -20,3 +21,23 @@ margin-left: 2ch; } } + +// Make the logo and title fit the site header. +.site-header { + .site-logo { + width: 3rem; + } + + // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above. + // Use the upstream `mq` media query mixin to target that breakpoint. + // https://just-the-docs.com/docs/utilities/responsive-modifiers/ + // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mi... + @include mq(md) { + .site-logo { + width: 5.5rem; + }
Is there a reason for this number, rather than just setting it back to 100%? Looks the same to me (since it gets flexed down to size anyway), and I'd prefer fewer magic numbers if possible!
+ .site-title { + font-size: 1.25rem !important; + } + } +}
We should pick (and document) a preferred order!
Agreed and noted for later.
.main-content { // Just the Docs puts titles next to definitions, rather than on @@ -20,3 +21,23 @@ margin-left: 2ch; } } + +// Make the logo and title fit the site header. +.site-header { + .site-logo { + width: 3rem; + } + + // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above. + // Use the upstream `mq` media query mixin to target that breakpoint. + // https://just-the-docs.com/docs/utilities/responsive-modifiers/ + // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mi... + @include mq(md) { + .site-logo { + width: 5.5rem; + }
Is there a reason for this number, rather than just setting it back to 100%? Yes, because 100% means different things for different screen sizes. The media queries seem to be used inconsistently upstream; different elements shift at different breakpoints... That may or may not be fixed by bumping the dependency, but that currently is precluded by build failures. Keeping the font size and logo size fixed doesn't produce surprises.
I recommend not to put too much energy into this in any case. Aligning the output style across the current website and "the docs" will likely make this obsolete one way or another eventually.
Valentin Gagarin <valentin@gagarin.work> writes:
We should pick (and document) a preferred order!
Agreed and noted for later.
.main-content { // Just the Docs puts titles next to definitions, rather than on @@ -20,3 +21,23 @@ margin-left: 2ch; } } + +// Make the logo and title fit the site header. +.site-header { + .site-logo { + width: 3rem; + } + + // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above. + // Use the upstream `mq` media query mixin to target that breakpoint. + // https://just-the-docs.com/docs/utilities/responsive-modifiers/ + // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mi... + @include mq(md) { + .site-logo { + width: 5.5rem; + }
Is there a reason for this number, rather than just setting it back to 100%? Yes, because 100% means different things for different screen sizes. The media queries seem to be used inconsistently upstream; different elements shift at different breakpoints... That may or may not be fixed by bumping the dependency, but that currently is precluded by build failures. Keeping the font size and logo size fixed doesn't produce surprises.
I recommend not to put too much energy into this in any case. Aligning the output style across the current website and "the docs" will likely make this obsolete one way or another eventually.
Alright, patch queued. Thank you!
This patch has been committed as 94a1be48baaec5da6bec9ac3dd6efd99cfb43665, which can be viewed online at https://spectrum-os.org/git/spectrum/commit/?id=94a1be48baaec5da6bec9ac3dd6e.... This is an automated message. Send comments/questions/requests to: Alyssa Ross <hi@alyssa.is>
participants (3)
-
Alyssa Ross -
Alyssa Ross -
Valentin Gagarin