docs

stereobooster · Dec 4, 2024 · efd81b3 · efd81b3
1 parent 03e5621
commit efd81b3
Show file tree

Hide file tree

Showing 18 changed files with 58 additions and 341 deletions.
diff --git a/README.md b/README.md
@@ -15,19 +15,10 @@ It should be easy to create documentation with many diagrams, like in [**B**yrne
 
 ## Status
 
-I have implemented core packages and added some examples. However, I still need to add more tests, configure CI, create a demo site, and address the remaining TODOs.
+I have implemented core packages and added some examples. However, I still need to add more tests, and address the remaining TODOs.
 
 ## Packages
 
-### Core
-
-- [x] [@beoe/rehype-code-hook](/packages/rehype-code-hook/)
-- [x] [@beoe/sqlitecache](/packages/sqlitecache/)
-- [x] [@beoe/cache](/packages/cache/)
-- [x] [@beoe/remark-code-hook](/packages/remark-code-hook/)
-- [x] [@beoe/pan-zoom](/packages/pan-zoom/)
-- [x] [@beoe/fenceparser](/packages/fenceparser/)
-
 ### Diagrams
 
 |          | rehype                                              |
@@ -42,11 +33,19 @@ I have implemented core packages and added some examples. However, I still need
 
 Ideas for other diagrams: [Text to Diagram](https://stereobooster.com/posts/text-to-diagram/).
 
+### Core
+
+- [x] [@beoe/rehype-code-hook](/packages/rehype-code-hook/)
+- [x] [@beoe/sqlitecache](/packages/sqlitecache/)
+- [x] [@beoe/cache](/packages/cache/)
+- [x] [@beoe/remark-code-hook](/packages/remark-code-hook/)
+- [x] [@beoe/pan-zoom](/packages/pan-zoom/)
+- [x] [@beoe/fenceparser](/packages/fenceparser/)
+
 ## Logo
 
 The logo is an illustration from [Oliver Byrne's Elements of Euclid: The First Six Books with Coloured Diagrams and Symbols](https://www.c82.net/euclid/).
 
 ## TODO
 
-- update readmes for all packages. Point to online documentation and remove duplication
 - online example for pan-zoom
diff --git a/experiments/rehype-pintora/README.md b/experiments/rehype-pintora/README.md
@@ -1,5 +1,5 @@
 # @beoe/rehype-pintora
 
-Rehype plugin to generate [Pintora](https://pintorajs.vercel.app/) diagrams (as inline SVGs) in place of code fences.
+Rehype plugin to generate [Pintora](https://pintorajs.vercel.app/) diagrams in place of code fences.
 
 Tried it out of curiosity (and it is kind of easy to do with `@beoe/rehype-code-hook`). Didn't like the result. And I don't have use case for it, so not gonna push it forward.
diff --git a/packages/demo/src/content/docs/diagrams/graphviz.mdx b/packages/demo/src/content/docs/diagrams/graphviz.mdx
@@ -111,6 +111,18 @@ You probaly want to use `inline` strategy and implement dark scheme via CSS:
 }
 ```
 
-### Tip
+## Tips
 
 `inline` strategy allows to use [interactivity](/start-here/interactivity/).
+
+### Transparent background
+
+To remove background use:
+
+````md
+```dot
+digraph G {
+ bgcolor="transparent"
+}
+```
+````
diff --git a/packages/demo/src/content/docs/diagrams/vizdom.mdx b/packages/demo/src/content/docs/diagrams/vizdom.mdx
@@ -61,7 +61,7 @@ digraph TD {
     Server -> Browser [style=dashed, arrowhead=none]
 }
 ```
- 
+
   </TabItem>
   <TabItem label="Markdown">
 
@@ -174,3 +174,9 @@ You probaly want to use `inline` strategy and implement dark scheme via CSS:
 ### Tip
 
 `inline` strategy allows to use [interactivity](/start-here/interactivity/).
+
+## Notes
+
+- HTML classes are not supported
+- Text is transformed to path, so <kbd>Cmd</kbd> + <kbd>F</kbd> doesn't work
+- Doesn't support some unicode chars, like `label="∅"`
diff --git a/packages/demo/src/content/docs/notes/graph-libraries.md b/packages/demo/src/content/docs/notes/graph-libraries.md
@@ -0,0 +1,10 @@
+---
+title: Graph libraries
+draft: true
+---
+
+- graphology is about 70kb uncompressed
+- `@dagrejs/graphlib` is about 12kb
+- [graph-data-structure](https://www.npmjs.com/package/graph-data-structure) is about 4kb (but it doesn't support ids for edges)
+- [DirectedGraph](https://data-structure-typed-docs.vercel.app/classes/DirectedGraph.html) is about 40kb
+- [Other options](https://www.npmjs.com/search?q=graph-theory)
diff --git a/...s/demo/src/content/docs/packages/index.md → ...ages/demo/src/content/docs/other/index.md b/...s/demo/src/content/docs/packages/index.md → ...ages/demo/src/content/docs/other/index.md
diff --git a/packages/demo/src/content/docs/start-here/configuration.md b/packages/demo/src/content/docs/start-here/configuration.md
@@ -6,11 +6,11 @@ sidebar:
 
 All Rehype diagram plugins support (at least) following configurations:
 
+- [`strategy`](/start-here/strategy/) (optional). Default `inline`
+- [`darkScheme`](/start-here/dark-scheme/) (optional). Default `undefined`
 - `cache` (optional) - Map-like storage to speed up consequent renders of page. You can use standard JS `Map`, but probably it is better to use [@beoe/cache](https://github.com/stereobooster/beoe/tree/main/packages/cache/).
 - `class` (optional) - allows to setup additional classes for diagrams. For example, `.not-content` for inline diagrams if you use [tailwindcss-typography](https://github.com/tailwindlabs/tailwindcss-typography)
 - `svgo` (optional) - options for [SVGO](https://github.com/svg/svgo). Use `false` to disable optimization with SVGO
-- [`strategy`](/start-here/strategy/) (optional). Default `inline`
-- [`darkScheme`](/start-here/dark-scheme/) (optional). Default `undefined`
 
 All configurations can be set either globally or locally (via fence-code meta). Global configurations applies to all diagrams. Local configurations applies only to one diagram. Local configurations always override global, with exception for `class` option (it applies all provided classes).
 

diff --git a/packages/rehype-d2/README.md b/packages/rehype-d2/README.md
@@ -1,6 +1,6 @@
 # @beoe/rehype-d2
 
-Rehype plugin to generate [d2](https://d2lang.com) diagrams (as inline SVGs) in place of code fences. This:
+Rehype plugin to generate [d2](https://d2lang.com) diagrams in place of code fences. This:
 
 ````md
 ```d2
@@ -35,11 +35,7 @@ const html = await unified()
   .process(`markdown`);
 ```
 
-It support caching the same way as [@beoe/rehype-code-hook](/packages/rehype-code-hook/) does.
-
-## TODO
-
-- [ ] documentation for options
+[Online documentation](https://beoe.stereobooster.com/diagrams/d2/) provides more details.
 
 ## Awaited features
 

diff --git a/packages/rehype-d2/package.json b/packages/rehype-d2/package.json
@@ -15,6 +15,7 @@
     "directory": "packages/rehype-d2"
   },
   "sideEffects": false,
+  "homepage": "https://beoe.stereobooster.com/diagrams/d2/",
   "exports": {
     "types": "./dist/index.d.js",
     "default": "./dist/index.js"

diff --git a/packages/rehype-gnuplot/README.md b/packages/rehype-gnuplot/README.md
@@ -1,6 +1,6 @@
 # @dat/rehype-gnuplot
 
-Rehype plugin to generate [Gnuplot](https://gnuplot.sourceforge.net/) diagrams (as inline SVGs) in place of code fences. This:
+Rehype plugin to generate [Gnuplot](https://gnuplot.sourceforge.net/) diagrams in place of code fences. This:
 
 ````md
 ```gnuplot
@@ -33,21 +33,4 @@ const html = await unified()
   .process(`markdown`);
 ```
 
-It support caching the same way as [@beoe/rehype-code-hook](/packages/rehype-code-hook/) does.
-
-## Tips
-
-### XKCD-style
-
-You can create XKCD-style plots with this [snippet](https://rfonseca.github.io/xkcd-gnuplot/). In order for it to work as SVG you need to changed following lines:
-
-```diff
-- set term postscript eps font 'HumorSans' fontfile 'Humor-Sans.pfa' 22
-- set output 'xkcd.eps'
-+ set terminal svg enhanced font "HumorSans,Patrick Hand,Chalkboard,Comic Sans MS,18"
-```
-
-You may use any font you like (don't forget to load it in HTML), for example:
-
-- [Humor Sans](https://github.com/shreyankg/xkcd-desktop/blob/master/Humor-Sans.ttf)
-- [Patrick Hand](https://fonts.google.com/specimen/Patrick+Hand)
+[Online documentation](https://beoe.stereobooster.com/diagrams/gnuplot/) provides more details.
diff --git a/packages/rehype-gnuplot/package.json b/packages/rehype-gnuplot/package.json
@@ -15,6 +15,7 @@
     "directory": "packages/rehype-gnuplot"
   },
   "sideEffects": false,
+  "homepage": "https://beoe.stereobooster.com/diagrams/gnuplot/",
   "exports": {
     "types": "./dist/index.d.js",
     "default": "./dist/index.js"

diff --git a/packages/rehype-graphviz/README.md b/packages/rehype-graphviz/README.md
@@ -1,6 +1,6 @@
 # @beoe/rehype-graphviz
 
-Rehype plugin to generate [Graphviz](https://graphviz.org/) diagrams (as inline SVGs) in place of code fences. This
+Rehype plugin to generate [Graphviz](https://graphviz.org/) diagrams in place of code fences. This
 
 ````md
 ```dot
@@ -33,71 +33,10 @@ const html = await unified()
   .process(`markdown`);
 ```
 
-It support caching the same way as [@beoe/rehype-code-hook](/packages/rehype-code-hook/) does.
-
-## Tips
-
-### Styling and dark mode
-
-You can add dark mode with something like this:
-
-```css
-:root {
-  --color-variable: #000;
-}
-@media (prefers-color-scheme: dark) {
-  :root {
-    --color-variable: #fff;
-  }
-}
-.graphviz {
-  text {
-    fill: var(--color-variable);
-  }
-  [fill="black"] {
-    fill: var(--color-variable);
-  }
-  [stroke="black"] {
-    stroke: var(--color-variable);
-  }
-}
-```
-
-Plus you can pass [class](https://graphviz.org/docs/attrs/class/) to Edges and Nodes to implement advanced styling.
-
-### Transparent background
-
-To remove background use:
-
-```dot
-digraph G {
- bgcolor="transparent"
-}
-```
-
-### To remove title
-
-To remove `title` (which shows as tooltip when you hover mouse) use:
-
-```dot
-digraph G {
- node[tooltip=" "]
-}
-```
-
-### You can add links
-
-Inline SVG can contain HTML links:
-
-```dot
-digraph G {
- node[URL="https://example.com"]
-}
-```
+[Online documentation](https://beoe.stereobooster.com/diagrams/graphviz/) provides more details.
 
 ## TODO
 
-- document new options
 - expose options to load font metrics and images
   - `Warning: no hard-coded metrics for 'Helvetica,Arial,sans-serif'.  Falling back to 'Times' metrics`
 - check `tred` and `unflatten` functions

diff --git a/packages/rehype-graphviz/package.json b/packages/rehype-graphviz/package.json
@@ -14,6 +14,7 @@
     "url": "git+https://github.com/stereobooster/beoe.git",
     "directory": "packages/rehype-graphviz"
   },
+  "homepage": "https://beoe.stereobooster.com/diagrams/graphviz/",
   "sideEffects": false,
   "exports": {
     "types": "./dist/index.d.js",

diff --git a/packages/rehype-mermaid/README.md b/packages/rehype-mermaid/README.md
@@ -24,12 +24,6 @@ flowchart LR
   start --> stop
 ```
 
-## How is it different from `rehype-mermaid`?
-
-There is battle-tested and well maintained [rehype-mermaid](https://github.com/remcohaszing/rehype-mermaid). Both plugins use the same [mermaid-isomorphic](https://github.com/remcohaszing/mermaid-isomorphic) behind the scene.
-
-Main **difference** is that this plugin supports cache, but less teted.
-
 ## Usage
 
 ```js
@@ -43,20 +37,4 @@ const html = await unified()
   .process(`markdown`);
 ```
 
-It support caching the same way as [@beoe/rehype-code-hook](/packages/rehype-code-hook/) does.
-
-## Tips
-
-### Playwright
-
-You need to install `playwright` as well. Also you probably need something like this:
-
-```json
-"scripts": {
-  "postinstall": "playwright install chromium"
-}
-```
-
-## TODO
-
-- write about dark mode
+[Online documentation](https://beoe.stereobooster.com/diagrams/mermaid/) provides more details.
diff --git a/packages/rehype-mermaid/package.json b/packages/rehype-mermaid/package.json
@@ -14,6 +14,7 @@
     "url": "git+https://github.com/stereobooster/beoe.git",
     "directory": "packages/rehype-mermaid"
   },
+  "homepage": "https://beoe.stereobooster.com/diagrams/mermaid/",
   "sideEffects": false,
   "exports": {
     "types": "./dist/index.d.js",

diff --git a/packages/rehype-plantuml/README.md b/packages/rehype-plantuml/README.md
@@ -1,6 +1,6 @@
 # @beoe/rehype-plantuml
 
-Rehype plugin to generate [plantuml](https://www.plantuml.com/) diagrams (as inline SVGs) in place of code fences. This:
+Rehype plugin to generate [plantuml](https://www.plantuml.com/) diagrams in place of code fences. This:
 
 ````md
 ```plantuml