Docs refresh (#109)

Redesign documentation site using Pico and makes a number of small changes to the docs, including some updated content for the homepage

docs/README.md

@@ -0,0 +1,3 @@
+# Blurry Docs
+
+The documentation site for Blurry.

docs/blurry.toml

@@ -11,6 +11,7 @@ url = 'https://johnfraney.ca'
 
 [blurry.schema_data.sourceOrganization]
 name = 'Blurry'
+url = 'https://blurry-docs.netlify.app'
 
 [blurry.template_schema_types]
 ContextWebPage = 'WebPage'

docs/blurry_docs/__init__.py

@@ -0,0 +1,33 @@
+from selectolax.lexbor import parse_fragment
+
+
+def body_to_cards(html: str):
+    """Creates grids of h3s and their contents using <article> tags"""
+    tree = parse_fragment(html)
+    is_in_card = False
+    html = ""
+
+    for index, node in enumerate(tree):
+        if node.tag == "h2":
+            if is_in_card:
+                html += "</article></div>"
+                is_in_card = False
+            # The next index is a text node (whitespace), so look two ahead
+            if tree[index + 2].tag == "h3":
+                html += node.html or ""
+                html += '<div class="flex-grid">'
+                continue
+
+        if node.tag == "h3":
+            if is_in_card:
+                html += "</article>"
+            html += "<article>"
+            is_in_card = True
+
+        html += node.html or ""
+
+        # This assumes that the Markdown content ends with a card
+        if node == tree[-1]:
+            html += "</article></div>"
+
+    return html

docs/content/commands/build.md

@@ -3,10 +3,13 @@
 name = "Commands: build"
 abstract = "Documentation for Blurry's build command"
 datePublished = 2023-04-09
+dateModified = 2024-01-03
 +++
 
 # Commands: build
 
+## Usage
+
 `build` builds a production-ready version of a Blurry static site.
 It outputs the site in the folder specified by the `build_directory_name` [setting](./../configuration/settings.md), which defaults to `./dist/`
 

docs/content/commands/runserver.md

@@ -3,10 +3,13 @@
 name = "Commands: runserver"
 abstract = "Documentation for Blurry's runserver command"
 datePublished = 2023-04-09
+dateModified = 2024-01-03
 +++
 
 # Commands: `runserver`
 
+## Usage
+
 This command is a nod to [Django's command of the same name](https://docs.djangoproject.com/en/latest/ref/django-admin/#runserver).
 It starts a development server on `http://127.0.0.1:8000` and live-reloads when source content changes.
 
@@ -15,13 +18,27 @@ It starts a development server on `http://127.0.0.1:8000` and live-reloads when
 - It is served on `f"http://{DEV_HOST}:{DEV_PORT}"`, which defaults to <http://127.0.0.1:8000/> and can be changed in the [settings](../configuration/settings.md)
 - The `RUNSERVER` setting is set to `True`, which can be useful in conditionally rendering analytics or ad tags in [templates](../templates/syntax.md)
 
-Its output looks something like:
+## Example
+
+`runserver`'s output looks something like:
 
 ```shell
 $ blurry runserver
-[I 230108 15:47:36 server:335] Serving on http://127.0.0.1:8000
-[I 230108 15:47:36 handlers:62] Start watching changes
-[I 230108 15:47:36 handlers:64] Start detecting changes
-Gathered 14 tasks (sitemap and 13 content files)
-Took 0.119001 seconds
+.  .             
+|-.| . ..-..-.. .
+`-''-'-''  '  '-|
+              `-'
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ Markdown Plugins    ┃ HTML Plugins ┃ Jinja Plugins ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│ container           │ minify_html  │ body_to_cards │
+│ punctuation         │              │ headings      │
+│ python_code         │              │ url_path      │
+│ python_code_in_list │              │ blurry_image  │
+└─────────────────────┴──────────────┴───────────────┘
+[I 250103 10:41:51 server:331] Serving on http://127.0.0.1:8000
+[I 250103 10:41:51 handlers:62] Start watching changes
+[I 250103 10:41:51 handlers:64] Start detecting changes
+Blurring 21 Markdown files and 6 other files
+Built site in 2.465286 seconds
 ```

docs/content/configuration/environment-variables.md

@@ -3,13 +3,18 @@
 name = "Configuration: environment variables"
 abstract = "Documentation for Blurry's settings configuration using environment variables"
 datePublished = 2023-04-09
+dateModified = 2024-01-03
 +++
 
 # Configuration: environment variables
 
 Blurry settings can be overridden using environment variables.
 
 For the setting you'd like to override, simply prefix the setting name with `BLURRY_`.
+(This prefix can be customized in your [`blurry.toml` file](./blurry.toml.md)).
+
+## Example
+
 To build your site for a different domain, for instance, set the `BLURRY_DOMAIN` environment variable:
 
 ```bash

docs/content/getting-started/quick-start.md

@@ -3,7 +3,7 @@
 name = "Getting started: quick start"
 abstract = "Documentation for how to get started with Blurry"
 datePublished = 2023-04-09
-dateModified = 2024-12-29
+dateModified = 2025-01-03
 +++
 
 # Getting started: quick start
@@ -41,7 +41,7 @@ Blurry's directory structure is used as the website's navigation structure, with
 
 - `index.md` files generate `index.html` files
 - other Markdown files, like `about.md`, generate a file like `about/index.html`, which makes for clean, SEO-friendly URLs
-- files that end with `.jinja` are processed with [Jinja](https://jinja.palletsprojects.com/en/stable/) and generate a file with the `.jinja` extension removed, like `feed.xml.jinja` -> `feed.xml`
+- files that end with `.jinja` are processed with [Jinja](https://jinja.palletsprojects.com/en/stable/) and generate a file with the `.jinja` extension removed, like `feed.xml.jinja` -> `feed.xml`. See [Content: dynamic](../content/dynamic.md)
 - images are copied and generated at multiple sizes. See [Content: Images](../content/images.md) for more information
 - other files are copied as-is
 

docs/content/index.md

@@ -1,51 +1,62 @@
 +++
-"@type" = "WebPage"
+"@type" = "WebSite"
 name = "Introduction"
-abstract = "A Python-powered static site generator with a focus on page speed and SEO."
+abstract = "An extensible static site generator with exceptional SEO and page speed."
 datePublished = 2023-04-09
 +++
 
-# Blurry: A Python-powered static site generator
+# Blurry: A static site generator for SEO and page speed
+
+<p style="text-align: center;">
+    <a href="/getting-started/quick-start/" class="right-arrow" role="button" rel="noreferrer">Get Started</a>
+</p>
 
 ## What is Blurry?
 
-Blurry is a static site generator with a terrible pun of a name: if you're generating static sight, you're making things Blurry.
+Blurry is a static site generator, like [Hugo](https://gohugo.io) or [Pelican](https://getpelican.com/), with a big pun of a name: if you're generating static sight, you're making things Blurry.
 
-Blurry brings the concept of schema-first development to static site generators.
-Specifically, Blurry uses [Schema.org](https://schema.org/) schema type names as the names for its template files, and schema type properties as Markdown front matter to populate those templates.
+If you're looking for a static site generator in Python that's as [easy to customize](./plugins/intro.md) as it is to use, give Blurry a try!
 
 ## Goals
 
-### SEO performance
+### 📈 SEO performance
 
 Blurry supports [Schema.org](https://schema.org/) and [Open Graph](https://ogp.me/) with zero configuration.
 This enables [rich Google results](https://developers.google.com/search/docs/appearance/structured-data/search-gallery) and [link previews](https://www.opengraph.xyz/) out-of-the-box.
 
-### Page speed
+### 🏎️ Page speed
 
 While using Blurry doesn't guarantee good page speed, it does solve a number of pain points that tend to slow down page loads.
 
 [Blurry's image handling](../content/images.md) and HTML minification, for instance, can help get you a 100/100 [PageSpeed](https://pagespeed.web.dev/) score if the rest of your site is fast.
 
-### Minimal configuration
+### ⚙ Minimal configuration
+
+Blurry has sensible defaults so you can spend less time configuring and more time writing.
 
-Blurry seeks to use sensible defaults so you can spend less time configuring and more time writing.
-A viable Blurry configuration file ([`blurry.toml`](./../configuration/blurry.toml.md)) can be as simple as:
+A viable [Blurry configuration file](./configuration/blurry.toml.md) can be as simple as:
 
 ```toml
 [blurry]
 domain = "johnfraney.ca"
 ```
 
-### Semantic HTML
+### 🧩 Exensibility
+
+Blurry supports [plugins](./plugins/intro.md) to make it easy to add functionality for:
+
+- [Markdown customization](./plugins/write-a-markdown-plugin.md)
+- Jinja [filters](./plugins/write-a-jinja-filter-plugin.md) & [extensions](./plugins/write-a-jinja-extension-plugin.md)
+- [HTML post-processing](./plugins/write-an-html-plugin.md)
+
+</article>
 
-Where applicable, Blurry tries to use semantic HTML elements like `<aside>` over more generic elements like `<div>`.
-Using semantic HTML elements also facilities classless CSS styling, which can be useful when styling some Markdown-generated HTML elements, and it can be [good for accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML), too.
+</div>
 
 ## Non-goals
 
-### "Gotta go fast!"
+### 🚄 "Gotta go fast!"
 
 While Blurry aims to be performant, build performance is not its top priority.
-It's written in Python, so it may not be able to compete on speed with other static site generators like [Hugo](https://gohugo.io/).
-Instead, it aims to be *fast enough* while taking advantage of the Python ecosystem.
+It's written in Python, so it _may_ not be able to compete on speed with other static site generators like [Hugo](https://gohugo.io/).
+Instead, it aims to be _fast_enough_ while optimizing for developer and user experience.

docs/content/plugins/intro.md

@@ -3,13 +3,14 @@
 name = "Plugins: intro"
 abstract = "Documentation for Blurry's plugin architecture"
 datePublished = 2023-04-15
+dateModified = 2024-01-03
 +++
 
 # Plugins: intro
 
 :::{info}
 This documentation covers how to write and register Blurry plugins.
-For documentation about custom Mistune plugins that Blurry ships with out-of-the-box, see [Content: Markdown](../content/markdown.md).
+For documentation about custom [Mistune](https://mistune.lepture.com/en/latest/) plugins that Blurry ships with out-of-the-box, see [Content: Markdown](../content/markdown.md).
 :::
 
 Blurry ships with a simple plugin infrastructure that makes it easy to write and register plugins that change how Blurry processes Markdown and HTML.
@@ -21,6 +22,7 @@ See the docs for the type of plugin you'd like to write:
 - [Plugins: write a Markdown plugin](./write-a-markdown-plugin.md)
 - [Plugins: write an HTML plugin](./write-an-html-plugin.md)
 - [Plugins: write a Jinja filter plugin](./write-a-jinja-filter-plugin.md)
+- [Plugins: write a Jinja extension plugin](./write-a-jinja-extension-plugin.md)
 
 ## How to register a plugin
 

docs/content/templates/components.md

@@ -3,11 +3,12 @@
 name = "Templates: components"
 abstract = "Documentation for Blurry's template components using JinjaX"
 datePublished = 2023-12-06
+dateModified = 2024-01-03
 +++
 
 # Templates: components
 
-Template components are written in [JinjaX](https://jinjax.scaletti.dev/) and should be placed in a `components` subdirectory of your templates directory, like:
+Template components are written in [JinjaX](https://jinjax.scaletti.dev/) and should have a file extension of `.jinja` and be placed in a `components` subdirectory of your templates directory, like:
 
 ```text
 templates/
@@ -18,4 +19,6 @@ templates/
 └── WebSite.html
 ```
 
+## More information
+
 For more information, see the JinjaX documentation at <https://jinjax.scaletti.dev/guide/>.

docs/content/templates/context.md

@@ -22,6 +22,7 @@ The template context variables are:
 | Variable(s)              | Description                                                                                    |
 | ------------------------ | ---------------------------------------------------------------------------------------------- |
 | `body`                   | an HTML string converted from Markdown                                                         |
+| `filepath`               | the Markdown file path for the current page                                                    |
 | `url`                    | the absolute URL for the given page                                                            |
 | `schema_type_tag`        | a `<script type="application/ld+json">` tag containing Schema.org markup                       |
 | `open_graph_tags`        | [Open Graph](https://ogp.me/) meta tags, like `<meta property="og:title" content="..." />`     |

docs/pyproject.toml

@@ -3,9 +3,6 @@ name = "blurry-docs"
 version = "0.1.0"
 description = ""
 authors = ["Your Name <you@example.com>"]
-readme = "README.md"
-package-mode = false
-packages = []
 
 [tool.poetry.dependencies]
 python = "^3.11"
@@ -14,3 +11,6 @@ blurry-cli = { path = "..", develop = true }
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.plugins."blurry.jinja_filter_plugins"]
+body_to_cards = "blurry_docs:body_to_cards"

docs/templates/ContextWebPage.html.jinja

@@ -1,10 +1,16 @@
-{% extends "base.html.jinja" %}
+{% extends "WebPage.html.jinja" %}
 
 {% block title %}{{ name }}{% endblock %}
 
 {% block body %}
 {{ body|safe }}
 
+<h3><code>url</code></h3>
+<pre><code class="language-text">{{ url|safe }}</code></pre>
+
+<h3><code>filepath</code></h3>
+<pre><code class="language-text">{{ filepath|safe }}</code></pre>
+
 <h3><code>schema_data</code></h3>
 <pre><code class="language-json">{{ schema_data|safe }}</code></pre>