revise some pages

bluefishjs · Sep 12, 2024 · af8ef86 · af8ef86
1 parent 9c588d7
commit af8ef86
Show file tree

Hide file tree

Showing 3 changed files with 25 additions and 102 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -23,8 +23,8 @@ export default defineConfig({
 
     sidebar: {
       "/learn": [
-        { text: "Get started", link: "/learn/get-started" },
-        { text: "What is Bluefish?", link: "/learn/what-is-bluefish" },
+        { text: "Get Started", link: "/learn/get-started" },
+        { text: "What Is Bluefish?", link: "/learn/what-is-bluefish" },
         {
           text: "Tutorial",
           items: [

diff --git a/docs/learn/get-started.md b/docs/learn/get-started.md
@@ -2,6 +2,11 @@
 
 ## Install
 
+Bluefish comes in two flavors: `bluefish-js` and `bluefish-solid`.
+
+`bluefish-js` is a pure-JS/TS library that works in any JavaScript environment.
+**Use this unless you are using SolidJS.**
+
 ::: code-group
 
 ```bash:no-line-numbers [yarn]
@@ -20,95 +25,9 @@ pnpm install bluefish-js
 bun add bluefish-js
 ```
 
-
-### Start REPLs
-
-We have REPLs to get you started for in many different environments and frameworks:
-
-- [Vanilla JS](https://playground.solidjs.com/anonymous/d19113c2-dab6-4867-9d2b-4c14040757b9)
-- Vanilla HTML **TODO**
-- [Observable](https://observablehq.com/@joshpoll/bluefish-in-observable)
-- [Svelte](https://svelte.dev/repl/1fa5bf8713ac4fc2a991560e50564932?version=4.2.1)
-- anywidget **TODO**
-- SolidJS **TODO**
-
-
 :::
 
-## Vanilla JS
-
-Here's a starter REPL: https://playground.solidjs.com/anonymous/d19113c2-dab6-4867-9d2b-4c14040757b9
-
-<!-- ::: sandbox
-
-```tsx [index.ts]
-import { render } from "solid-js/web";
-import * as bluefish from "@bluefish-js/solid";
-
-const { Bluefish, Background, StackH, StackV, Circle, Text, Ref, Distribute, Align, Arrow } = bluefish.Hyperscript;
-
-function App() {
-  return Bluefish(
-    /* Bluefish is a diagramming library for the web */
-    /* You can specify UI-like components such as Background and StackH */
-    Background({ padding: 20 },
-      StackH({ spacing: 50 },
-        Circle({ name: "mercury", r: 15, fill: "#EBE3CF", "stroke-width": 3, stroke: "black" }),
-        Circle({ r: 36, fill: "#DC933C", "stroke-width": 3, stroke: "black" }),
-        Circle({ r: 38, fill: "#179DD7", "stroke-width": 3, stroke: "black" }),
-        Circle({ r: 21, fill: "#F1CF8E", "stroke-width": 3, stroke: "black" }),
-      )
-    ),
-    /* But you can also use *relations* like Align and Distribute */
-    Align({ alignment: "centerX" },
-      Text({ name: "label" }, "Mercury"),
-      /* Bluefish lets you refer to previous components using a special \`Ref\` component. */
-      Ref({ select: "mercury" }),
-    ),
-    Distribute({ direction: "vertical", spacing: 60 },
-      Ref({ select: "label" }),
-      Ref({ select: "mercury" }),
-    ),
-    /* In addition to performing layout, Bluefish relations can also draw objects. */
-    Arrow(
-      Ref({ select: "label" }),
-      Ref({ select: "mercury" }),
-    )
-  )
-}
-
-render(App, document.getElementById("app"));
-```
-
-::: -->
-
-
-## Vanilla HTML
-
-**TODO**
-
-## Observable notebook
-
-Here's a starter notebook: https://observablehq.com/@joshpoll/bluefish-in-observable.
-
-<iframe
-  width="100%"
-  height="261"
-  frameBorder="0"
-  src="https://observablehq.com/embed/@joshpoll/bluefish-in-observable@37?cells=planets"
-/>
-
-## Svelte
-
-Here's a starter REPL: https://svelte.dev/repl/1fa5bf8713ac4fc2a991560e50564932?version=4.2.1.
-
-## anywidget
-
-**TODO**
-
-## SolidJS
-
-Bluefish has special support for SolidJS. Use the `bluefish-solid` package:
+`bluefish-solid` offers Bluefish as a SolidJS component library using JSX syntax.
 
 ::: code-group
 
@@ -130,6 +49,13 @@ bun add bluefish-solid
 
 :::
 
-Bluefish can then be used with SolidJS's JSX syntax.
+### Starter REPLs
+
+We have REPLs to get you started in some common environments and frameworks:
 
-Here's a starter REPL: **TODO**
+- [Vanilla JS](https://playground.solidjs.com/anonymous/d19113c2-dab6-4867-9d2b-4c14040757b9)
+- Vanilla HTML **TODO**
+- [Observable](https://observablehq.com/@joshpoll/bluefish-in-observable)
+- [Svelte](https://svelte.dev/repl/1fa5bf8713ac4fc2a991560e50564932?version=4.2.1)
+- anywidget **TODO**
+- SolidJS **TODO**
diff --git a/docs/learn/what-is-bluefish.md b/docs/learn/what-is-bluefish.md
@@ -70,19 +70,16 @@ const members = [
 ];
 </script>
 
-# What is Bluefish?
+# What Is Bluefish?
 
-Bluefish is a diagramming framework for the web. In contrast to previous frameworks, which focus on
-low-level or high-level abstractions, Bluefish draws inspiration from UI component frameworks like React that
-let users define and use their own custom abstractions (i.e. components).
+Bluefish is a diagramming framework for the web. It relaxes the UI component model popularized by
+React. The main primitive of Bluefish is the _relation_. Just as components are the
+building blocks of user interfaces, relations are the building blocks of diagrams. Unlike
+components, relations can share children with other relations, and they don't need to fully specify
+their childrens' layouts.
 
-The main primitive of Bluefish is the _relation_. Just as components are the building blocks of user
-interfaces, relations are the building blocks of diagrams. Unlike components, relations can share
-children with other relations, and they don't need to fully specify their childrens' layouts.
-
-Bluefish
-is based on work from the [MIT Visualization Group](https://vis.csail.mit.edu/) and the [Software
-Design Group](https://sdg.csail.mit.edu/). You can read more
+Bluefish is based on work from the [MIT Visualization Group](https://vis.csail.mit.edu/) and the [Software
+is based on work from the [MIT Visualization Group](https://vis.csail.mit.edu/) and the [Software Design Group](https://sdg.csail.mit.edu/). You can read more
 about the theory, design, and implementation of Bluefish in our [research
 paper](https://arxiv.org/abs/2307.00146).