ENH: Add ABlog support

docs/conf.py

@@ -13,17 +13,19 @@
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-    "jupyter_sphinx",
-    "matplotlib.sphinxext.plot_directive",
-    "myst_nb",
-    # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
-    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinxext.rediraffe",
     "sphinx_design",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    # For extension examples and demos
+    "ablog",
+    "jupyter_sphinx",
+    "matplotlib.sphinxext.plot_directive",
+    "myst_nb",
+    # "nbsphinx",  # Uncomment and comment-out MyST-NB for local testing purposes.
+    "numpydoc",
     "sphinx_togglebutton",
 ]
 
@@ -145,7 +147,19 @@
         "sidebar-nav-bs",
         "custom-template",
     ],  # This ensures we test for custom sidebars
-    "demo/no-sidebar": [],  # Test what page looks like with no sidebar items
+    "demo/no-sidebar": [],  # Test what page looks like with no sidebar items,
+    # Blog sidebars
+    # ref: https://ablog.readthedocs.io/manual/ablog-configuration-options/#blog-sidebars
+    "demo/blog/*": [
+        "postcard.html",
+        "recentposts.html",
+        "tagcloud.html",
+        "categories.html",
+        "authors.html",
+        "languages.html",
+        "locations.html",
+        "archives.html",
+    ],
 }
 
 myst_heading_anchors = 2
@@ -161,6 +175,14 @@
     "contributing.rst": "contribute/index.rst",
 }
 
+# ABlog configuration
+blog_path = "demo/blog/index"
+blog_authors = {
+    "pydata": ("PyData", "https://pydata.org"),
+    "jupyter": ("Jupyter", "https://jupyter.org"),
+}
+
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/demo/ablog.md

@@ -0,0 +1,24 @@
+# Blogs with `ABlog`
+
+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.
+
+This theme has styling support for ABlog, and demonstrates some of its functionality here.
+
+## Example blog
+
+Click below to go to the blog
+
+```{button-link} blog/index.html
+:color: primary
+Go to the blog
+```
+
+## Example post list
+
+```{postlist}
+:list-style: circle
+:category: Manual
+:format: "{title}"
+:sort:
+```

docs/demo/blog/post1.md

@@ -0,0 +1,16 @@
+---
+blogpost: true
+date: Jan 01, 2022
+author: pydata
+location: World
+category: Manual
+language: English
+---
+
+# Post title 1
+
+Here's some text for post 1!
+
+## Post 1 section
+
+Some more text for post 1's section

docs/demo/blog/post2.md

@@ -0,0 +1,16 @@
+---
+blogpost: true
+date: Jan 02, 2022
+author: jupyter
+location: World
+category: Manual
+language: English
+---
+
+# Post title 2
+
+Here's some text for post 2!
+
+## Post 2 section
+
+Some more text for post 2's section

docs/demo/blog/post3.md

@@ -0,0 +1,16 @@
+---
+blogpost: true
+date: Jan 03, 2022
+author: jupyter
+location: World
+category: Manual
+language: English
+---
+
+# Post title 3
+
+Here's some text for post 3!
+
+## Post 3 section
+
+Some more text for post 3's section

docs/demo/index.rst

@@ -20,6 +20,7 @@ See the sections to the left and below to explore.
     kitchen-sink/index
     theme-elements
     pydata
+    ablog
     api
 
 

pyproject.toml

@@ -50,6 +50,7 @@ doc = [
   "sphinxext-rediraffe",
   "sphinx-sitemap",
   # For demo examples
+  "ablog",
   "jupyter_sphinx",
   "pandas",
   "plotly",

src/pydata_sphinx_theme/assets/styles/extensions/_ablog.scss

@@ -0,0 +1,51 @@
+/**
+ * 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 {
+  > h3,
+  > h2 {
+    margin-top: 1rem;
+  }
+
+  > ul {
+    list-style: none;
+    padding-left: 0;
+  }
+}
+
+// HACK: ABlog articles always seem to have the structure:
+// <section id="POST-TITLE-ID">{{ POST CONTENT }}
+// <div class="section">
+//   <div class="section"
+//      <span>previous button
+//      <span>empty space
+//      <span>next button
+//
+// So these rules make that assumption
+article.bd-article > section + div.section {
+  font-size: 1.2em;
+
+  span:first-child:before {
+    content: "\f104";
+    font-family: "Font Awesome 5 Free";
+    font-weight: 800;
+  }
+
+  span:last-child:after {
+    content: "\f105";
+    font-family: "Font Awesome 5 Free";
+    font-weight: 800;
+  }
+}
+
+// The post list on the ablog index
+.ablog-post {
+  ul.ablog-archive {
+    padding-left: 0;
+  }
+}

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -68,6 +68,7 @@ $grid-breakpoints: (
 @import "./content/math";
 
 // Content blocks from Sphinx extensions
+@import "./extensions/ablog";
 @import "./extensions/bootstrap";
 @import "./extensions/copybutton";
 @import "./extensions/ethical-ads";