From f7e1f4648285cb487a058d374f78154a9330f261 Mon Sep 17 00:00:00 2001 From: Kattni Date: Mon, 25 Aug 2025 02:25:55 -0400 Subject: [PATCH 01/12] Fixes. --- .../assets/stylesheets/beeware_theme.css | 62 ++++++++++++++++- .../overrides/partials/nav.html | 68 ++++++++++++++----- 2 files changed, 109 insertions(+), 21 deletions(-) diff --git a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css index 7b63c18..91e92c8 100644 --- a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css +++ b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css @@ -335,9 +335,30 @@ color: unset; } -/* Version number wrap */ -span.version_number { +/* Sidebar title font size */ +.site-name, .site-name-small { + font-size: 18px; +} + +/* Version number */ +.version-number { overflow-wrap: anywhere; + font-size: 12px; + font-weight: normal; +} + +.version-number-small { + font-size: 12px; + font-weight: normal; + width: 125px; + float: right; + overflow-wrap: anywhere; + padding-top: 10px; +} + +/* Separates site name and version number */ +.site-name { + padding-bottom: 8px; } /* GitHub sidebar links */ @@ -351,10 +372,20 @@ span.version_number { margin-top: 1rem; } -.github-links:last-of-type { +.github-links:last-of-type, .github-links-small:last-of-type { margin-bottom: 1rem; } +.github-links-small:first-of-type { + margin-top: 3rem; +} + +.github-links-small { + font-weight: normal; + margin-top: 0.5rem; + margin-bottom: 0.5rem; +} + /* Shows the logo in the sidebar */ .md-nav__title .md-nav__button { display: unset; @@ -366,6 +397,13 @@ span.version_number { height: unset; padding-bottom: 1rem; } + .logo-small img { + height: 60px !important; + float: left; + padding-left: 8px; + padding-right: 16px; + padding-bottom: 0 !important; + } } /* Adjusts sidebar title block, which includes GitHub links */ @@ -473,3 +511,21 @@ input.md-search__input, .md-search__suggest, .md-search-result__meta { footer.md-footer *, html .md-footer-meta.md-typeset a { color: light-dark(#343A40, #E2E4E9); } + +/* Footer navigation */ +.md-footer__inner { + padding: 0; +} +.md-footer__link { + margin-bottom: 0; + margin-top: 0.5rem; +} +.md-footer__title { + font-size: .6rem; +} +.md-footer__direction { + font-size: .6rem +} +.md-footer__button { + margin: 0 0 0.2rem 0; +} diff --git a/src/beeware_docs_tools/overrides/partials/nav.html b/src/beeware_docs_tools/overrides/partials/nav.html index 5df39c2..fd3b6d7 100644 --- a/src/beeware_docs_tools/overrides/partials/nav.html +++ b/src/beeware_docs_tools/overrides/partials/nav.html @@ -34,25 +34,57 @@ From 4996b67e6d560eebdfa6282021646fbc9f2d1881 Mon Sep 17 00:00:00 2001 From: Kattni Date: Mon, 25 Aug 2025 04:52:01 -0400 Subject: [PATCH 02/12] Final fixes, update demo to verify changes. --- docs/en/index.md | 37 +++++---- docs/en/section_one/index.md | 16 +++- docs/en/section_one/page_two.md | 2 +- docs/en/section_two/index.md | 2 +- pyproject.toml | 1 - .../assets/stylesheets/beeware_theme.css | 44 +++++----- .../overrides/partials/nav.html | 82 ++++++++----------- 7 files changed, 93 insertions(+), 91 deletions(-) diff --git a/docs/en/index.md b/docs/en/index.md index 6262081..b0f7a36 100644 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -2,34 +2,43 @@ ## Theme checklist -Things to manually check: +This demo is designed to test the various features of the BeeWare +MkDocs Material theme overrides. Please read through and verify +that everything listed on this and the following pages is present +and functioning as detailed in the description. -### Titlebar +## Titlebar A medium-gray titlebar is on the page. This the theme template has been applied. -### Header and logo icons +## Header icon The header icon top-left has been rendered. This confirms the template can reference external resources. -The logo icon in the left sidebar has been rendered. This confirms the -sidebar will render properly on the target sites. +## Homepage sidebar icon -### Heading font +The logo icon in the left sidebar has been rendered. The logo should be +the width of, and of equal height to, the sidebar. The site title should +be rendered below it in slightly larger font than the rest of the +sidebar, with the version number below it in smaller font. + +This confirms the sidebar will render properly on the target sites. + +## Heading font Headings are rendered in Cutive. This confirms the BeeWare custom CSS theme has been applied. -### Inline Code +## Inline code Inline code is rendered in the same color as the surrounding font. This confirms that the theme has not caused any undesired changes. This is text with `inline code` here and `inline code` here. -### Tabbed Content Code +## Tabbed content code Code is in a contrasting color to the background. Copy button should copy only the commands; the prompt should not be included. @@ -61,7 +70,7 @@ C:\...>git clone https://github.com/beeware/beeware-theme.git /// -### Code copy button behavior +## Code copy button behavior The copy button on the following codeblock should result in `from pathlib import Path` being copied to the clipboard. @@ -81,14 +90,14 @@ docs pyproject.toml requirements.docs.txt LICENSE README.md src ``` -### Sidebar links +## Sidebar links Sidebar links exist, and point to the `beeware-docs-tools` repo. This confirms that the sidebar content has been loaded, and the `project-name` has been set in the MkDocs configuration file, and the version number is computed and added. -### Link colors +## Link colors This link to [the main BeeWare website](https://beeware.org) should be blue in *both* light mode and dark mode. @@ -98,7 +107,7 @@ The links in the left and right sidebars should also be blue in both modes. When scrolling down the page, the active header link in the right sidebar should be light blue in dark mode, and darker blue in light mode. -### Translation Admonition +## Translation admonition The English-language version of this document should show the "Translations are available" admonition below. The French translation should show the "This is @@ -143,7 +152,7 @@ machine translation, or not translated at all. {% endif %} -### Custom 404 page +## Custom 404 page Add `nopage` to the end of the URL in your browser to verify the 404 page contains two flying bees, and the text "Brutus can't find what @@ -152,7 +161,7 @@ you're looking for" below. *MkDocs builds fail with unrecognized internal links, so you need to manually verify this check by modifying the URL in your browser.* -### Next Checks +## Next checks The following link should take you to BeeWare Docs Tools Demo Section One. It is included to verify cross-page linking. diff --git a/docs/en/section_one/index.md b/docs/en/section_one/index.md index 2fbd98a..687ee23 100644 --- a/docs/en/section_one/index.md +++ b/docs/en/section_one/index.md @@ -1,6 +1,14 @@ -# BeeWare Docs Tools Demo Section One +# BeeWare Docs Tools Demo section one -## Include External Markdown from a Local File +## Non-homepage sidebar logo + +The logo icon in the left sidebar should be small on all pages other than the +homepage. The site title and version number should be rendered next to it with +the site title in slightly larger font, and the version number in smaller font. + +This verifies that the theme is being properly applied. + +## Include external markdown from a local file The following section should have only a header, and a paragraph with inline code followed by a code block. There should be no text between the code block and the @@ -9,7 +17,7 @@ local files. -8<- "include_content.md:local-content" -## Include External Markdown from a URL +## Include external markdown from a URL The following section should have only a header, some text and a Markdown list. This verifies that the external include extension is working, and that @@ -19,6 +27,6 @@ This verifies that the external include extension is working, and that https://raw.githubusercontent.com/beeware/beeware-docs-tools/refs/heads/main/docs/include_content.md:remote-content -8<- -## Footer Navigation +## Footer navigation Navigate to *Section One - Page Two* for the final check. diff --git a/docs/en/section_one/page_two.md b/docs/en/section_one/page_two.md index ccab504..fcc9c7a 100644 --- a/docs/en/section_one/page_two.md +++ b/docs/en/section_one/page_two.md @@ -1,4 +1,4 @@ -# BeeWare Docs Tools Demo Section One: Page Two +# BeeWare Docs Tools Demo section one: page two ### Footer and navigation links diff --git a/docs/en/section_two/index.md b/docs/en/section_two/index.md index 5de8e1f..f1299ea 100644 --- a/docs/en/section_two/index.md +++ b/docs/en/section_two/index.md @@ -1,4 +1,4 @@ -# BeeWare Docs Tools Demo Section Two +# BeeWare Docs Tools Demo section two ### Images subdirectory diff --git a/pyproject.toml b/pyproject.toml index 243bbf7..23498af 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,7 +26,6 @@ dependencies = [ "markdown-checker==0.2.5", "mistletoe==1.4.0", "mkdocs-autorefs==1.4.2", - "mkdocs-include-markdown-plugin==7.1.6", "mkdocs-literate-nav==0.6.2", "mkdocs-macros-plugin==1.3.9", "mkdocs-material==9.6.17", diff --git a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css index 91e92c8..3b2866e 100644 --- a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css +++ b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css @@ -336,7 +336,7 @@ } /* Sidebar title font size */ -.site-name, .site-name-small { +.site-name { font-size: 18px; } @@ -347,43 +347,41 @@ font-weight: normal; } -.version-number-small { +.small .version-number { font-size: 12px; font-weight: normal; - width: 125px; - float: right; overflow-wrap: anywhere; padding-top: 10px; + width: 157px; + float: right; } -/* Separates site name and version number */ +/* Site name */ .site-name { padding-bottom: 8px; } -/* GitHub sidebar links */ -.github-links { - font-weight: normal; - margin-top: 0.5rem; - margin-bottom: 0.5rem; +.small .site-name { + padding-bottom: 0; } -.github-links:first-of-type { - margin-top: 1rem; +/* Sidebar title block */ +.sidebar-title-block { + margin-bottom: 1.2rem; } -.github-links:last-of-type, .github-links-small:last-of-type { - margin-bottom: 1rem; +.small .sidebar-title-block{ + height: 60px; } -.github-links-small:first-of-type { - margin-top: 3rem; +/* GitHub sidebar links */ +.github-links { + font-weight: normal; } -.github-links-small { - font-weight: normal; +.github-link-block a:last-child .github-links { margin-top: 0.5rem; - margin-bottom: 0.5rem; + margin-bottom: 1rem; } /* Shows the logo in the sidebar */ @@ -397,7 +395,8 @@ height: unset; padding-bottom: 1rem; } - .logo-small img { + + .md-nav__title.small .sidebar-logo img { height: 60px !important; float: left; padding-left: 8px; @@ -435,6 +434,11 @@ body { font-size: 1rem; } +/* Shifts the footer down to regain screen-space on pages with short content */ +.md-content { + min-height: 81vh; +} + /* Read the Docs elements font size fix */ readthedocs-flyout, readthedocs-notification, diff --git a/src/beeware_docs_tools/overrides/partials/nav.html b/src/beeware_docs_tools/overrides/partials/nav.html index fd3b6d7..c3446ff 100644 --- a/src/beeware_docs_tools/overrides/partials/nav.html +++ b/src/beeware_docs_tools/overrides/partials/nav.html @@ -33,58 +33,40 @@ > -