From d7b1f41ca54b1fb803375d386a5fd4b95acd3416 Mon Sep 17 00:00:00 2001
From: Joel Drapper <joel@drapper.me>
Date: Wed, 4 Sep 2024 14:19:48 +0100
Subject: [PATCH] Loads more changes to docs

---
 .vitepress/config.mts                      | 42 +++++++++-----
 design/index.md                            |  3 +
 design/intro.md                            |  3 -
 guides/v2-upgrade.md                       | 33 +++++++++++
 {guide => handbook}/advanced-components.md |  0
 {guide => handbook}/attributes.md          |  0
 {guide => handbook}/first-component.md     |  0
 {guide => handbook}/index.md               |  0
 {guide => handbook}/layouts.md             |  0
 {guide => handbook}/rails/views.md         |  0
 {guide => handbook}/setup.md               |  0
 {guide => handbook}/tags.md                |  0
 {guide => handbook}/under-the-hood.md      |  0
 index.md                                   |  7 ++-
 reference/html.md                          | 24 +++++++-
 reference/index.md                         |  1 +
 reference/sgml.md                          | 66 +++++++++++++++++++++-
 reference/svg.md                           |  6 +-
 18 files changed, 163 insertions(+), 22 deletions(-)
 create mode 100644 design/index.md
 delete mode 100644 design/intro.md
 create mode 100644 guides/v2-upgrade.md
 rename {guide => handbook}/advanced-components.md (100%)
 rename {guide => handbook}/attributes.md (100%)
 rename {guide => handbook}/first-component.md (100%)
 rename {guide => handbook}/index.md (100%)
 rename {guide => handbook}/layouts.md (100%)
 rename {guide => handbook}/rails/views.md (100%)
 rename {guide => handbook}/setup.md (100%)
 rename {guide => handbook}/tags.md (100%)
 rename {guide => handbook}/under-the-hood.md (100%)
 create mode 100644 reference/index.md

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 3f990ae..c568825 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -7,7 +7,7 @@ export default defineConfig({
 		nav: [
 			{ text: "Home", link: "/" },
 			{ text: "Community", link: "project/community" },
-			{ text: "Guide", link: "/guide" },
+			{ text: "Handbook", link: "/handbook" },
 		],
 		sidebar: [
 			{
@@ -18,22 +18,35 @@ export default defineConfig({
 					{ text: "GitHub", link: "https://github.com/phlex-ruby" },
 				],
 			},
+
 			{
-				text: "Guide",
+				text: "Handbook",
+				link: "/handbook/",
 				collapsed: false,
 				items: [
-					{ text: "Intro", link: "/guide/" },
-					{ text: "Setup", link: "/guide/setup" },
-					{ text: "Your first component", link: "/guide/first-component" },
-					{ text: "Under the hood", link: "/guide/under-the-hood" },
-					{ text: "Attributes deep-dive", link: "/guide/attributes" },
-					{ text: "Advanced components", link: "/guide/advanced-components" },
-					{ text: "Tags", link: "/guide/tags" },
-					{ text: "Layouts", link: "/guide/layouts" },
+					{ text: "Intro", link: "/handbook/" },
+					{ text: "Setup", link: "/handbook/setup" },
+					{ text: "Your first component", link: "/handbook/first-component" },
+					{ text: "Under the hood", link: "/handbook/under-the-hood" },
+					{ text: "Attributes deep-dive", link: "/handbook/attributes" },
+					{
+						text: "Advanced components",
+						link: "/handbook/advanced-components",
+					},
+					{ text: "Tags", link: "/handbook/tags" },
+					{ text: "Layouts", link: "/handbook/layouts" },
 				],
 			},
+
+			{
+				text: "Guides",
+				collapsed: false,
+				items: [{ text: "Upgrading to v2", link: "/guides/v2-upgrade" }],
+			},
+
 			{
 				text: "Reference",
+				link: "/reference/",
 				collapsed: false,
 				items: [
 					{ text: "SGML", link: "/reference/sgml" },
@@ -51,16 +64,17 @@ export default defineConfig({
 					},
 				],
 			},
+
 			{
 				text: "Technical Design",
-				collapsed: false,
+				collapsed: true,
 				items: [
 					{ text: "Intro", link: "/design/intro" },
 					{ text: "Caching", link: "/design/caching" },
 					{ text: "Performance", link: "/design/performance" },
-					{ text: "Component Kits" },
-					{ text: "Rails Integration" },
-					{ text: "Selective Rendering" },
+					{ text: "Component kits" },
+					{ text: "Rails integration" },
+					{ text: "Selective rendering" },
 					{ text: "Deferred Render" },
 				],
 			},
diff --git a/design/index.md b/design/index.md
new file mode 100644
index 0000000..cb59dc2
--- /dev/null
+++ b/design/index.md
@@ -0,0 +1,3 @@
+# Technical Design
+
+This is a space to go into a little more detail about the technical design of some of the more interesting parts of Phlex. This is worth reading if you’re interested in understanding how Phlex works and maybe considering contributing to the project.
diff --git a/design/intro.md b/design/intro.md
deleted file mode 100644
index 47fb48f..0000000
--- a/design/intro.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Technical Design
-
-This is a space to go into a little more detail about the technical design of some parts of Phlex. This is worth reading if you’re interested in understanding how Phlex works and maybe considering contributing to the project.
diff --git a/guides/v2-upgrade.md b/guides/v2-upgrade.md
new file mode 100644
index 0000000..837c2cf
--- /dev/null
+++ b/guides/v2-upgrade.md
@@ -0,0 +1,33 @@
+# Upgrading to v2
+
+While we’ve tried to keep breaking changes to a minimum, there are a few things you will need to be aware of when upgrading from Phlex v1 to v2.
+
+The latest version of v1 contains a number of deprecations, so we recommend upgrading to the latest version of v1 first.
+
+## Breaking changes
+
+### `template` → `view_template`
+
+Instead of defining the `template` method for your component templates, you should instead define `view_template`.
+
+### `template_tag` → `template`
+
+To render [`<template>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template) elements in a `Phlex::HTML` component, you need to call the `template` method instead of the original `template_tag` method.
+
+### We removed `tokens` and `classes`
+
+If you need these back, you can always copy their original implementation from here, paste them into a helper module and include it in your `ApplicationComponent`.
+
+However, we recommend using the new standard capabilities of attributes.
+
+## New features
+
+### Kits
+
+Originally previewed in v1, kits are now out of beta and fully supported in v2. Kits are a way to package up a set of components into a module.
+
+### Selective rendering
+
+### A better cache
+
+Phlex v2 introduces a new attribute cache that caches more things. We wrote about some of the technical details [here](/design/caching).
diff --git a/guide/advanced-components.md b/handbook/advanced-components.md
similarity index 100%
rename from guide/advanced-components.md
rename to handbook/advanced-components.md
diff --git a/guide/attributes.md b/handbook/attributes.md
similarity index 100%
rename from guide/attributes.md
rename to handbook/attributes.md
diff --git a/guide/first-component.md b/handbook/first-component.md
similarity index 100%
rename from guide/first-component.md
rename to handbook/first-component.md
diff --git a/guide/index.md b/handbook/index.md
similarity index 100%
rename from guide/index.md
rename to handbook/index.md
diff --git a/guide/layouts.md b/handbook/layouts.md
similarity index 100%
rename from guide/layouts.md
rename to handbook/layouts.md
diff --git a/guide/rails/views.md b/handbook/rails/views.md
similarity index 100%
rename from guide/rails/views.md
rename to handbook/rails/views.md
diff --git a/guide/setup.md b/handbook/setup.md
similarity index 100%
rename from guide/setup.md
rename to handbook/setup.md
diff --git a/guide/tags.md b/handbook/tags.md
similarity index 100%
rename from guide/tags.md
rename to handbook/tags.md
diff --git a/guide/under-the-hood.md b/handbook/under-the-hood.md
similarity index 100%
rename from guide/under-the-hood.md
rename to handbook/under-the-hood.md
diff --git a/index.md b/index.md
index 7ccccdd..f9618d1 100644
--- a/index.md
+++ b/index.md
@@ -8,8 +8,11 @@ hero:
   tagline: A little string concatenation library.
   actions:
     - theme: brand
-      text: Guide
-      link: /guide
+      text: Handbook
+      link: /handbook/
+    - theme: alt
+      text: Reference
+      link: /reference/
 
 features:
   - title: Pure, beautiful Ruby
diff --git a/reference/html.md b/reference/html.md
index 647811a..9ae4c11 100644
--- a/reference/html.md
+++ b/reference/html.md
@@ -1 +1,23 @@
-# HTML
+# `Phlex::HTML` < [`Phlex::SGML`](sgml.md)
+
+## Instance methods
+
+We’re not going to list them all here, but `Phlex::HTML` defines an instance method for every non-deprecated HTML element. See the MDN Web Docs for a [complete list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element).
+
+### `#doctype`
+
+This outputs an [HTML5 doctype](https://developer.mozilla.org/en-US/docs/Glossary/Doctype) declaration:
+
+```
+<!doctype html>
+```
+
+### `#svg`
+
+The `#svg` method is special because it yields an instance of [`Phlex::SVG`](svg.md) to the block. This allows you to create SVG content directly in your HTML:
+
+```ruby
+svg do |svg|
+  svg.circle cx: 50, cy: 50, r: 40, fill: "red"
+end
+```
diff --git a/reference/index.md b/reference/index.md
new file mode 100644
index 0000000..cf5aa07
--- /dev/null
+++ b/reference/index.md
@@ -0,0 +1 @@
+# Reference
diff --git a/reference/sgml.md b/reference/sgml.md
index 9762715..f69808b 100644
--- a/reference/sgml.md
+++ b/reference/sgml.md
@@ -1 +1,65 @@
-# SGML
+# `Phlex::SGML`
+
+`Phlex::SGML` (which stands for [Standard Generalized Markup Language](https://en.wikipedia.org/wiki/Standard_Generalized_Markup_Language)) is the superclass of `Phlex::HTML` and `Phlex::SVG`. It provides a common interface for both HTML and SVG components.
+
+You can use this interface by subclassing either `Phlex::HTML` or `Phlex::SVG` with your own component class.
+
+## Class methods
+
+### `.new`
+
+It’s worth noting that `Phlex::SGML` overrides `.new` in order to capture the block during instantiation. This block will not be passed on to your `#initialize` method. Instead, it is passed to your `#view_template` method when the component is rendered.
+
+### `.register_element`
+
+Allows you to define a custom element that can be used in your templates. Since this defines an instance method, it’s inherited by subclasses.
+
+```ruby{2,5}
+class MyComponent < Phlex::HTML
+  register_element :trix_editor
+
+  def view_template
+    trix_editor
+  end
+end
+```
+
+## Instance methods
+
+### `#after_template`
+
+### `#around_template`
+
+### `#await`
+
+### `#before_template`
+
+### `#call`
+
+### `#capture`
+
+### `#comment`
+
+### `#comment`
+
+### `#context`
+
+### `#flush`
+
+### `#format_object`
+
+### `#plain`
+
+### `#render?`
+
+### `#render`
+
+### `#tag`
+
+### `#unsafe_raw`
+
+### `#unsafe_tag`
+
+### `#vanish`
+
+### `#whitespace`
diff --git a/reference/svg.md b/reference/svg.md
index 941fc48..fc1719d 100644
--- a/reference/svg.md
+++ b/reference/svg.md
@@ -1 +1,5 @@
-# SVG
+# `Phlex::SVG` < [`Phlex::SGML`](sgml.md)
+
+## Instance methods
+
+We’re not going to list them all here, but `Phlex::SVG` defines an instance method for every non-deprecated SVG element. See the MDN Web Docs for a [complete list](https://developer.mozilla.org/en-US/docs/Web/SVG).