diff --git a/docs/conf.py b/docs/conf.py index 6872a4371..5ec5f3e2b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -156,14 +156,14 @@ # Blog sidebars # ref: https://ablog.readthedocs.io/manual/ablog-configuration-options/#blog-sidebars "examples/blog/*": [ - "postcard.html", - "recentposts.html", - "tagcloud.html", - "categories.html", - "authors.html", - "languages.html", - "locations.html", - "archives.html", + "ablog/postcard.html", + "ablog/recentposts.html", + "ablog/tagcloud.html", + "ablog/categories.html", + "ablog/authors.html", + "ablog/languages.html", + "ablog/locations.html", + "ablog/archives.html", ], } diff --git a/docs/user_guide/ablog.md b/docs/user_guide/ablog.md index ca79e78dc..327b88c0f 100644 --- a/docs/user_guide/ablog.md +++ b/docs/user_guide/ablog.md @@ -3,6 +3,10 @@ The [ABlog extension](https://ablog.readthedocs.io/) allows you to tag pages as **blog posts** and additionally include them in landing pages for your blog. It also has a number of sidebar templates to show off collections of your posts. +:::{admonition} Minimum version ABlog v0.11.0 +Make sure you have `ABlog>=0.11.0rc2` in your dependencies. +::: + This theme has styling support for ABlog, and demonstrates some of its functionality here. ## Example blog diff --git a/pyproject.toml b/pyproject.toml index 5a248f33d..a0135a727 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,7 +53,7 @@ doc = [ "sphinxext-rediraffe", "sphinx-sitemap", # For examples section - "ablog", + "ablog>=0.11.0rc2", "jupyter_sphinx", "pandas", "plotly", diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_ablog.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_ablog.scss index 762552d9a..192e823f3 100644 --- a/src/pydata_sphinx_theme/assets/styles/extensions/_ablog.scss +++ b/src/pydata_sphinx_theme/assets/styles/extensions/_ablog.scss @@ -2,20 +2,25 @@ * ABlog * ref: https://ablog.readthedocs.io/ */ -// HACK: ABlog has no CSS selector, but directly inserts elements into the sidebar -// So we make an assumption here that any *top-level* sidebar items that are ul/h2/h3 -// Are attached to ABlog. This is hacky and we should try to get top-level ablog -// CSS wrappers into ABlog instead. -.bd-sidebar-primary .sidebar-start-items__item { - > h3, - > h2 { + +/** + * Sidebar template components + */ +.ablog-sidebar-item { + h2, + h3 { + font-size: var(--pst-sidebar-header-font-size); // Remove unnecessary vertical whitespace margin-top: 0.5rem; - // Headers are too big by default - font-size: 1.7rem; + + // The headers are all links, but this makes them hard to parse + // So we change the colors to make them look like headers + a { + color: var(--pst-color-text-base); + } } - > ul { + ul { // No bullet points for the primary sidebar items list-style: none; padding-left: 0; @@ -25,100 +30,102 @@ display: flex; flex-direction: column; gap: 0.5em; + margin-bottom: 0; // The ablog cloud should move horizontally &.ablog-cloud { flex-direction: row; flex-flow: wrap; - gap: 0; - } - } -} + gap: 0.25rem; -// Vertical-align tag clouds -ul.ablog-cloud { - li { - // Center the tag cloud items - display: flex; - align-items: center; + // Vertical-align tag clouds + li { + // Center the tag cloud items + display: flex; + align-items: center; + } + } } } -// HACK: ABlog articles always seem to have the structure: -//
{{ POST CONTENT }} -//
-//
previous button -// empty space -// next button -// -// So these rules make that assumption -article.bd-article > section + div.section { +/** + * Previous / next buttons at the bottom + */ +.ablog__prev-next { font-size: 1.2em; + display: flex; + padding: 1rem 0; // The bottom previous / next arrows - span { + > span { // To ensure that the whole thing fits on one line even if there are long titles - max-width: 45%; - // Alignment with the prev/next arrows display: flex; - gap: 0.5rem; - align-items: center; - // Remove the ABlog icons because we specify our own - a i { - display: none; - } - // If the span is empty, it means there's no previous/next page to go to - // so this prevents the arrow from showing up - &:empty { - display: none; + max-width: 45%; + + // Links within each span have the collection of icon + text + a { + display: flex; + align-items: center; + margin-left: auto; + gap: 1rem; + line-height: 1.5rem; + + i:before { + color: var(--pst-color-text-base); + } } } - // The first span is the "previous" button - span:first-child:before { - content: var(--pst-icon-angle-left); - font-family: "Font Awesome 6 Free"; - font-weight: 800; + // The first span is for the previous page and aligns to the left + span.ablog__prev { + i.fa-arrow-circle-left:before { + content: var(--pst-icon-angle-left); + } } // The second span is just an empty space so we remove it because we're // positioning with flex - span:first-child + span { - display: none !important; + span.ablog__spacer { + display: none; } // The third span is aligned to the right - span:last-child { + span.ablog__next { + margin-left: auto; text-align: right; - &:after { + + i.fa-arrow-circle-right:before { content: var(--pst-icon-angle-right); - font-family: "Font Awesome 6 Free"; - font-weight: 800; } } } -// Post metadata that is on the "posts" page -ul.ablog-archive { - padding-left: 0; - font-size: 1.25rem; -} - -// The post list when you use the {postlist} directive -ul.postlist { +/** + * {postlist} directive and posts page + */ +.ablog__collection, +.postlist { padding-left: 0; - li.ablog-post { + .ablog-post { list-style: none; + // Post metadata + .ablog-archive { + list-style: none; + padding-left: 0; + } + // Title line should be a bit bigger .ablog-post-title { + margin-top: 0; font-size: 1.5rem; } - // Create a bit more whitespace if there's an excerpt - .ablog-post-excerpt { - margin-bottom: 2em; + + // Read more button should be a bit bigger + .ablog-post-expand { + font-size: 1.25rem; + margin-bottom: 0.5rem; } } } diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss index 39d54ff5f..421ec381d 100644 --- a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss +++ b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss @@ -34,6 +34,14 @@ } } + // Headers shouldn't be colored in the sidebars and some extensions add headers + h1, + h2, + h3, + h4 { + color: var(--pst-color-text-base); + } + .sidebar-start-items__item, .sidebar-end-items__item { padding: 0.5rem 0;