Added blog

.gitignore

@@ -119,3 +119,6 @@ tests/snapshot_tests/output
 
 # Sandbox folder - convenient place for us to develop small test apps without leaving the repo
 sandbox/
+
+# Cache of screenshots used in the docs
+.screenshot_cache

Makefile

@@ -11,8 +11,10 @@ format:
 format-check:
 	black --check src
 docs-serve:
+	rm -rf .screenshot_cache
 	mkdocs serve
 docs-build:
 	mkdocs build
 docs-deploy:
+	rm -rf .screenshot_cache
 	mkdocs gh-deploy

docs/api/index.md

@@ -0,0 +1,3 @@
+# Reference
+
+A reference to the Textual public APIs.

docs/blog/.authors.yml

@@ -0,0 +1,4 @@
+willmcgugan:
+  name: Will McGugan
+  description: CEO / code-monkey
+  avatar: https://github.com/willmcgugan.png

docs/blog/index.md

@@ -0,0 +1,3 @@
+# Textual Blog
+
+Welcome to the Textual blog, where we post about the latest releases and developments in the Textual world.

docs/blog/posts/helo-world.md

@@ -0,0 +1,19 @@
+---
+draft: false 
+date: 2022-11-06
+categories:
+  - News
+authors:
+  - willmcgugan
+---
+
+# New Blog
+
+Welcome to the first post on the Textual blog.
+
+<!-- more -->
+
+I plan on using this as a place to make announcements regarding new releases of Textual, and any other relevant news.
+
+The first piece of news is that we've reorganized this site a little. The Events, Styles, and Widgets references are now under "Reference", and what used to be under "Reference" is now "API" which contains API-level documentation. I hope that's a little clearer than it used to be!
+

docs/events/index.md

@@ -1,3 +1,5 @@
 # Events
 
 A reference to Textual [events](../guide/events.md).
+
+See the links to the left of the page, or in the hamburger menu (three horizontal bars, top left).

docs/help.md

@@ -1,20 +1,16 @@
----
-hide:
-  - navigation
----
-
 # Help
 
-Here's where to go if you need help with Textual.
+If you need help with any aspect of Textual, let us know! We would be happy to hear from you.
 
 ## Bugs and feature requests
 
 Report bugs via GitHub on the Textual [issues](https://github.com/Textualize/textual/issues) page. You can also post feature requests via GitHub issues, but see the [roadmap](./roadmap.md) first.
 
+## Discord Server
+
+For more realtime feedback or chat, join our discord server to connect with the [Textual community](https://discord.gg/Enf6Z3qhVr).
+
 ## Forum
 
 Visit the [Textual forum](https://community.textualize.io/) for Textual (and Rich) discussions.
 
-## Discord Server
-
-For more realtime feedback or chat, join our discord server to connect with the [Textual community](https://discord.gg/Enf6Z3qhVr).

docs/reference/index.md

@@ -1,3 +1,35 @@
 # Reference
 
-A reference to the Textual public APIs.
+Welcome to the Textual Reference.
+
+<div class="grid cards" markdown>
+
+-   :octicons-book-16:{ .lg .middle } __Events__
+
+    ---
+
+    Events are how Textual communicates with your application.
+
+    :octicons-arrow-right-24: [Events Reference](../events/index.md)
+
+
+-   :octicons-book-16:{ .lg .middle } __Styles__
+
+    ---
+
+    All the styles you can use to take your Textual app to the next level.
+
+    [:octicons-arrow-right-24: Styles Reference](../styles/index.md)
+
+
+-   :octicons-book-16:{ .lg .middle } __Widgets__
+
+    ---
+
+    How to use the many widgets builtin to Textual.
+
+    :octicons-arrow-right-24: [Widgets Reference](../widgets/index.md)
+
+  
+
+</div>

docs/roadmap.md

@@ -1,3 +1,9 @@
+---
+hide:
+  - navigation
+---
+
+
 # Roadmap
 
 We ([textualize.io](https://www.textualize.io/)) are actively building and maintaining Textual. 

docs/styles/index.md

@@ -1,3 +1,5 @@
 # Styles
 
 A reference to Widget [styles](../guide/styles.md).  
+
+See the links to the left of the page, or in the hamburger menu (three horizontal bars, top left).

docs/widgets/button.md

@@ -55,4 +55,4 @@ _No other attributes_
 
 ## See Also
 
-* [Button](../reference/button.md) code reference
+* [Button](../api/button.md) code reference

docs/widgets/checkbox.md

@@ -29,7 +29,7 @@ The example below shows checkboxes in various states.
 ## Reactive Attributes
 
 | Name    | Type   | Default | Description                        |
-|---------|--------|---------|------------------------------------|
+| ------- | ------ | ------- | ---------------------------------- |
 | `value` | `bool` | `False` | The default value of the checkbox. |
 
 ## Messages
@@ -43,7 +43,7 @@ The `Checkbox.Changed` message is sent when the checkbox is toggled.
 #### Attributes
 
 | attribute | type   | purpose                        |
-|-----------|--------|--------------------------------|
+| --------- | ------ | ------------------------------ |
 | `value`   | `bool` | The new value of the checkbox. |
 
 ## Additional Notes
@@ -54,4 +54,4 @@ The `Checkbox.Changed` message is sent when the checkbox is toggled.
 
 ## See Also
 
-- [Checkbox](../reference/checkbox.md) code reference
+- [Checkbox](../api/checkbox.md) code reference

docs/widgets/footer.md

@@ -39,4 +39,4 @@ This widget sends no messages.
 
 ## See Also
 
-* [Footer](../reference/footer.md) code reference
+* [Footer](../api/footer.md) code reference

docs/widgets/header.md

@@ -32,4 +32,4 @@ This widget sends no messages.
 
 ## See Also
 
-* [Header](../reference/header.md) code reference
+* [Header](../api/header.md) code reference

docs/widgets/index.md

@@ -1,3 +1,5 @@
 # Widgets
 
 A reference to the builtin [widgets](../guide/widgets.md).
+
+See the links to the left of the page, or in the hamburger menu (three horizontal bars, top left).

docs/widgets/input.md

@@ -54,7 +54,7 @@ The `Input.Submitted` message is sent when you press ++enter++ with the text fie
 #### Attributes
 
 | attribute | type  | purpose                          |
-|-----------|-------|----------------------------------|
+| --------- | ----- | -------------------------------- |
 | `value`   | `str` | The new value in the text input. |
 
 
@@ -64,4 +64,4 @@ The `Input.Submitted` message is sent when you press ++enter++ with the text fie
 
 ## See Also
 
-* [Input](../reference/input.md) code reference
+* [Input](../api/input.md) code reference

docs/widgets/static.md

@@ -31,4 +31,4 @@ This widget sends no messages.
 
 ## See Also
 
-* [Static](../reference/static.md) code reference
+* [Static](../api/static.md) code reference

mkdocs.yml

@@ -7,6 +7,7 @@ nav:
   - Introduction:
     - "index.md"
     - "getting_started.md"
+    - "help.md"
   - "tutorial.md"
   - Guide:
     - "guide/index.md"
@@ -24,97 +25,100 @@ nav:
     - "guide/animation.md"
     - "guide/screens.md"
   - "roadmap.md"
-  - Events:
-    - "events/index.md"
-    - "events/blur.md"
-    - "events/descendant_blur.md"
-    - "events/descendant_focus.md"
-    - "events/enter.md"
-    - "events/focus.md"
-    - "events/hide.md"
-    - "events/key.md"
-    - "events/leave.md"
-    - "events/load.md"
-    - "events/mount.md"
-    - "events/mouse_capture.md"
-    - "events/click.md"
-    - "events/mouse_down.md"
-    - "events/mouse_move.md"
-    - "events/mouse_release.md"
-    - "events/mouse_scroll_down.md"
-    - "events/mouse_scroll_up.md"
-    - "events/mouse_up.md"
-    - "events/paste.md"
-    - "events/resize.md"
-    - "events/screen_resume.md"
-    - "events/screen_suspend.md"
-    - "events/show.md"
-  - Styles:
-    - "styles/index.md"
-    - "styles/align.md"
-    - "styles/background.md"
-    - "styles/border.md"
-    - "styles/box_sizing.md"
-    - "styles/color.md"
-    - "styles/content_align.md"
-    - "styles/display.md"
-    - "styles/dock.md"
-    - "styles/grid.md"
-    - "styles/height.md"
-    - "styles/layer.md"
-    - "styles/layers.md"
-    - "styles/layout.md"
-    - "styles/links.md"
-    - "styles/margin.md"
-    - "styles/max_height.md"
-    - "styles/max_width.md"
-    - "styles/min_height.md"
-    - "styles/min_width.md"
-    - "styles/offset.md"
-    - "styles/opacity.md"
-    - "styles/outline.md"
-    - "styles/overflow.md"
-    - "styles/padding.md"
-    - "styles/scrollbar.md"
-    - "styles/scrollbar_gutter.md"
-    - "styles/scrollbar_size.md"
-    - "styles/text_align.md"
-    - "styles/text_style.md"
-    - "styles/text_opacity.md"
-    - "styles/tint.md"
-    - "styles/visibility.md"
-    - "styles/width.md"
-  - Widgets:
-    - "widgets/index.md"
-    - "widgets/button.md"
-    - "widgets/checkbox.md"
-    - "widgets/data_table.md"
-    - "widgets/footer.md"
-    - "widgets/header.md"
-    - "widgets/input.md"
-    - "widgets/static.md"
-    - "widgets/tree_control.md"
   - Reference:
-    - "reference/app.md"
-    - "reference/button.md"
-    - "reference/color.md"
-    - "reference/containers.md"
-    - "reference/dom_node.md"
-    - "reference/events.md"
-    - "reference/footer.md"
-    - "reference/geometry.md"
-    - "reference/header.md"
     - "reference/index.md"
-    - "reference/message_pump.md"
-    - "reference/message.md"
-    - "reference/pilot.md"
-    - "reference/query.md"
-    - "reference/reactive.md"
-    - "reference/screen.md"
-    - "reference/static.md"
-    - "reference/timer.md"
-    - "reference/widget.md"
-  - "help.md"
+    - Events:
+      - "events/index.md"
+      - "events/blur.md"
+      - "events/descendant_blur.md"
+      - "events/descendant_focus.md"
+      - "events/enter.md"
+      - "events/focus.md"
+      - "events/hide.md"
+      - "events/key.md"
+      - "events/leave.md"
+      - "events/load.md"
+      - "events/mount.md"
+      - "events/mouse_capture.md"
+      - "events/click.md"
+      - "events/mouse_down.md"
+      - "events/mouse_move.md"
+      - "events/mouse_release.md"
+      - "events/mouse_scroll_down.md"
+      - "events/mouse_scroll_up.md"
+      - "events/mouse_up.md"
+      - "events/paste.md"
+      - "events/resize.md"
+      - "events/screen_resume.md"
+      - "events/screen_suspend.md"
+      - "events/show.md"
+    - Styles:
+      - "styles/index.md"
+      - "styles/align.md"
+      - "styles/background.md"
+      - "styles/border.md"
+      - "styles/box_sizing.md"
+      - "styles/color.md"
+      - "styles/content_align.md"
+      - "styles/display.md"
+      - "styles/dock.md"
+      - "styles/grid.md"
+      - "styles/height.md"
+      - "styles/layer.md"
+      - "styles/layers.md"
+      - "styles/layout.md"
+      - "styles/links.md"
+      - "styles/margin.md"
+      - "styles/max_height.md"
+      - "styles/max_width.md"
+      - "styles/min_height.md"
+      - "styles/min_width.md"
+      - "styles/offset.md"
+      - "styles/opacity.md"
+      - "styles/outline.md"
+      - "styles/overflow.md"
+      - "styles/padding.md"
+      - "styles/scrollbar.md"
+      - "styles/scrollbar_gutter.md"
+      - "styles/scrollbar_size.md"
+      - "styles/text_align.md"
+      - "styles/text_style.md"
+      - "styles/text_opacity.md"
+      - "styles/tint.md"
+      - "styles/visibility.md"
+      - "styles/width.md"
+    - Widgets:
+      - "widgets/index.md"
+      - "widgets/button.md"
+      - "widgets/checkbox.md"
+      - "widgets/data_table.md"
+      - "widgets/footer.md"
+      - "widgets/header.md"
+      - "widgets/input.md"
+      - "widgets/static.md"
+      - "widgets/tree_control.md"
+  - API:
+    - "api/app.md"
+    - "api/button.md"
+    - "api/color.md"
+    - "api/containers.md"
+    - "api/dom_node.md"
+    - "api/events.md"
+    - "api/footer.md"
+    - "api/geometry.md"
+    - "api/header.md"
+    - "api/index.md"
+    - "api/message_pump.md"
+    - "api/message.md"
+    - "api/pilot.md"
+    - "api/query.md"
+    - "api/reactive.md"
+    - "api/screen.md"
+    - "api/static.md"
+    - "api/timer.md"
+    - "api/widget.md"
+  - "Blog":
+    - blog/index.md
 
 
 
@@ -170,13 +174,14 @@ theme:
       name: Switch to dark mode
   - media: "(prefers-color-scheme: dark)"
     scheme: slate
-    primary: black
+    primary: indigo
     toggle:
       icon: material/weather-night
       name: Switch to light mode
 
 plugins:
 
+- blog:
 - search:
 - autorefs:
 - mkdocstrings:

src/textual/_doc.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import hashlib
 import os
+from pathlib import Path
 import shlex
 from typing import Iterable
 
@@ -9,6 +11,9 @@ from textual.pilot import Pilot
 from textual._import_app import import_app
 
 
+SCREENSHOT_CACHE = ".screenshot_cache"
+
+
 # This module defines our "Custom Fences", powered by SuperFences
 # @link https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences
 def format_svg(source, language, css_class, options, md, attrs, **kwargs) -> str:
@@ -74,6 +79,22 @@ def take_svg_screenshot(
     if title is None:
         title = app.title
 
+    screenshot_cache = Path(SCREENSHOT_CACHE)
+    screenshot_cache.mkdir(exist_ok=True)
+
+    def get_cache_key(app: App) -> str:
+        hash = hashlib.md5()
+        file_paths = [app_path] + app.css_path
+        for path in file_paths:
+            with open(path, "rb") as source_file:
+                hash.update(source_file.read())
+        cache_key = f"{hash.hexdigest()}.svg"
+        return cache_key
+
+    screenshot_path = screenshot_cache / get_cache_key(app)
+    if screenshot_path.exists():
+        return screenshot_path.read_text()
+
     async def auto_pilot(pilot: Pilot) -> None:
         app = pilot.app
         await pilot.press(*press)
@@ -85,6 +106,9 @@ def take_svg_screenshot(
         auto_pilot=auto_pilot,
         size=terminal_size,
     )
+
+    screenshot_path.write_text(svg)
+
     assert svg is not None
 
     return svg