chore: update readmes (#22)

.github/workflows/release.yml

@@ -39,7 +39,7 @@ jobs:
         run: pnpm run build
 
       - name: Publish to NPM
-        run: pnpm -r publish --access public --tag alpha --no-git-checks
+        run: pnpm -r publish --access public --no-git-checks
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
           NPM_CONFIG_PROVENANCE: true

README.md

@@ -1,27 +1,41 @@
 <p align="center">
+<a href="https://kitbook.vercel.app/">
 <img src="https://raw.githubusercontent.com/jacob-8/kitbook/b96f77da81309a6ccd06693beb0f06ba8fdc0a2b/packages/kitbook/static/kitbook.svg" height="80" style="padding: 20px 0;">
+</a>
 </p>
 
 <p align="center">
-Documentation and Prototyping Workbench Tool for SvelteKit apps built with SvelteKit.
+Documentation, Prototyping, Inspection & Testing Workbench Tool for SvelteKit apps built with SvelteKit.
 <p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/kitbook"><img alt="version" src="https://img.shields.io/npm/v/kitbook?color=729B1B&label="></a>
 <p>
 
 <p align="center">
- <a href="https://kitbook.vercel.app/">View the Kitbook used to document and build Kitbook itself</a>
+ <a href="https://kitbook.vercel.app/">View the Kitbook Docs (and demo)</a>
 </p>
 
-## Kitbook Monorepo
-- Read the [Kitbook README](packages/kitbook/README.md) for features, examples, and more
-
 ## Contributing
 
+Would love to have you help! Read the [[0-roadmap|Roadmap]] for good places to start. We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
 [![Open in Codeflow](https://developer.stackblitz.com/img/open_in_codeflow.svg)](https:///pr.new/jacob-8/kitbook)
 
+Or work on Kitbook locally:
+
+- `pnpm i`
+- `pnpm stub`
+- `pnpm dev`
+
+To update the Kitbook code while using it in your own app, you can change your `devDependency` to point to it instead of npm by using something like `"kitbook": "link:../../../kitbook/packages/kitbook",` then run `pnpm package:watch` in Kitbook to keep it updating on changes. 
+
+*If you want to commit that changed package.json dependency reference without breaking CI builds, you can change your build script to `pnpm install -F site kitbook && vite build`.*
+
+---
 
-## svelte-pieces
+*If you're looked for Svelte Pieces, it has been moved to its own repository [here](https://github.com/jacob-8/svelte-pieces).*
 
-Moved to its own repository [here](https://github.com/jacob-8/svelte-pieces)
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[0-roadmap|Roadmap]: packages/kitbook/src/docs/9-maintainer-notes/0-roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

packages/kitbook/README.md

@@ -1,36 +1,41 @@
 <p align="center">
-<img src="https://raw.githubusercontent.com/jacob-8/kitbook/b96f77da81309a6ccd06693beb0f06ba8fdc0a2b/packages/kitbook/static/kitbook.svg" height="80" alt="Kitbook" style="padding: 20px 0;">
+<a href="https://kitbook.vercel.app/">
+<img src="https://raw.githubusercontent.com/jacob-8/kitbook/b96f77da81309a6ccd06693beb0f06ba8fdc0a2b/packages/kitbook/static/kitbook.svg" height="80" style="padding: 20px 0;">
+</a>
 </p>
 
 <p align="center">
-Documentation and Prototyping Workbench Tool for SvelteKit apps built with SvelteKit.
+Documentation, Prototyping, Inspection & Testing Workbench Tool for SvelteKit apps built with SvelteKit.
 <p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/kitbook"><img alt="version" src="https://img.shields.io/npm/v/kitbook?color=729B1B&label="></a>
 <p>
 
 <p align="center">
- <a href="https://kitbook.vercel.app/">View the Kitbook used to document and build Kitbook itself</a>
+ <a href="https://kitbook.vercel.app/">View the Kitbook Docs (and demo)</a>
 </p>
 
-# Kitbook Features
+## Contributing
 
-- File-based sidebar tree structure
-- MDSvex (Markdown + Svelte Components) to enable easy documenation as you build
-- Easy knobs allow for adjusting a component's view state (special thanks @rixo's Svench and Rich Harris' svelte-knobby!)
-- Quickly compare a single componenet across numerous different states 
+Would love to have you help! Read the [[0-roadmap|Roadmap]] for good places to start. We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
-## Examples
+[![Open in Codeflow](https://developer.stackblitz.com/img/open_in_codeflow.svg)](https:///pr.new/jacob-8/kitbook)
 
-| Example | Source | Playground |
-| ------- | ------ | ---------- |
-| [Kitbook's Kitbook](https://kitbook.vercel.app/)  | [GitHub](https://github.com/jacob-8/kitbook/tree/main/packages/kitbook)  | [Play Online](https://stackblitz.com/github/jacob-8/kitbook/tree/main/packages/kitbook) |
-| [Kitbook Template](https://kitbook-template.vercel.app/) (navigate to the simple example in a sub-route)  | [GitHub](https://github.com/jacob-8/kitbook/tree/main/packages/template) (in Kitbook monorepo)  | [Play Online](https://stackblitz.com/github/jacob-8/kitbook/tree/main/packages/template) |
-| [Svelte Pieces Kitbook](https://svelte-pieces.vercel.app/)  | [GitHub](https://github.com/jacob-8/kitbook/tree/main/packages/svelte-pieces) (in Kitbook monorepo)  | [Play Online](https://stackblitz.com/github/jacob-8/kitbook/tree/main/packages/svelte-pieces) |
-| [Living Dictionaries Kitbook](https://ld-parts.vercel.app/)  | [GitHub](https://github.com/livingtongues/living-dictionaries/tree/main/packages/parts)  | [Play Online](https://stackblitz.com/github/livingtongues/living-dictionaries/tree/main/packages/parts) |
-| [SvelteFireTS Kitbook](https://sveltefirets.vercel.app/)  | [GitHub](https://github.com/jacob-8/sveltefirets/tree/main/packages/demo)  | [Play Online](https://stackblitz.com/github/jacob-8/sveltefirets/tree/main/packages/demo) |
+Or work on Kitbook locally:
 
-## Contributing
+- `pnpm i`
+- `pnpm stub`
+- `pnpm dev`
+
+To update the Kitbook code while using it in your own app, you can change your `devDependency` to point to it instead of npm by using something like `"kitbook": "link:../../../kitbook/packages/kitbook",` then run `pnpm package:watch` in Kitbook to keep it updating on changes. 
+
+*If you want to commit that changed package.json dependency reference without breaking CI builds, you can change your build script to `pnpm install -F site kitbook && vite build`.*
+
+---
+
+*If you're looked for Svelte Pieces, it has been moved to its own repository [here](https://github.com/jacob-8/svelte-pieces).*
 
-Contributions are welcome! After cloning down the monorepo, with pnpm installed on your machine, run `pnpm i` and `pnpm dev` to get started.
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[0-roadmap|Roadmap]: src/docs/9-maintainer-notes/0-roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

packages/kitbook/src/docs/1-get-started.md

@@ -1,12 +1,10 @@
 # Get Started
 
-**Warning: This is alpha software and the API will change.** Please use if you like powerful tools, like scanning release notes for breaking changes, and like contributing to fix bugs. Please don't use if you don't like the above, but you can read the [[4-roadmap]] for clues on when things will be more stable.
-
 ## How to Add Kitbook to Your SvelteKit App
 
 Kitbook has a lot of powerful features, but let's start with the bare minimum to just get going:
 
-- `npm install -D kitbook@alpha` or `pnpm add -D kitbook@alpha`
+- `npm install -D kitbook` or `pnpm add -D kitbook`
 
 - Add the `kitbook()` Vite plugin *before* your `sveltekit()` plugin:
 	```js twoslash title="vite.config.js" {3,7}
@@ -24,32 +22,32 @@ Kitbook has a lot of powerful features, but let's start with the bare minimum to
 
 	*You can pass optional configuration settings to the plugin. You will see them referenced throughout the docs and you can read the types if you want to utilize them.*
 
-- Run your dev server as normal (`npm run dev`) and Kitbook will add a `src/routes/kitbook` folder to add a `/kitbook` route to your app - leave these files alone. 
+- Run your dev server as normal (`npm run dev`) and Kitbook will add a `src/routes/kitbook` folder to add a `/kitbook` route to your app. At this point you can navigate to the `/kitbook` route and see all your Svelte components, *including `+page.svelte` and `+layout.svelte` files as they are just Svelte components with a very important `data` prop*.
 
-	At this point you can navigate to the `/kitbook` route and see all your Svelte components, *including `+page.svelte` and `+layout.svelte` files - they are also Svelte components with a very important `data` prop*.
+If you don't have any app shell components in your root layout file, (e.g. a header), then your routes folder structure is probably good. However, if you have app shell components, then you'll notice that your Kitbook is also inheriting them. This won't work and you may need to adjust your folder structure to look like this:
 
-	If you don't have any app shell components in your root layout file, (e.g. a header), then your routes folder structure is probably good. However, if you have app shell components, then you'll notice that your Kitbook is also inheriting them. This won't work and you may need to adjust your folder structure to look like this:
+```txt {2,6}
+src/routes/
+│ (app)/
+│ ├ dashboard/
+│ ├ item/
+│ └ +layout.svelte <-- add app shell components like headers and initialize app only items, like db connections (refers to all layout files like +layout.ts)
+│ kitbook/
+└ +layout.svelte <-- initialize everything both your app and Kitbook need, like i18n 
+```
 
-	```txt {2,6}
-	src/routes/
-	│ (app)/
-	│ ├ dashboard/
-	│ ├ item/
-	│ └ +layout.svelte <-- add app shell components like headers and initialize app only items, like db connections (refers to all layout files like +layout.ts)
-	│ kitbook/
-	└ +layout.svelte <-- initialize everything both your app and Kitbook need, like i18n 
-	```
+You may find it a bit jarring to have your component workbench included in your main app. Kitbook originally worked as a companion app, like all previous art does, but this created a lot of friction:
+- Starting two dev servers is a pain and you will find yourself only working in Kitbook or only in your app, but not both which is the sweet spot. 
+- Set up the component workbench with just the right scaffolding to match the main app is a pain. It's annoying to have to keep everything in sync (like i18n) for example. The layout structure above makes it easy to clearly specify what context is needed for components and what is app only. 
+- The status checks for Playwright E2E tests running against Vercel deployments breaks down when your app deployment finishes before your Kitbook workbench deployment. 
+
+Furthermore the combined app + Kitbook approach is the only way to get the [[2-viewer]] tool which is a huge benefit. Let's move on to learn about Kitbook's [[2-viewer]] tool which bridges the gap between our app and our component workbench. 
+
+---
 
-	You may find it a bit jarring to have your component workbench included in your main app. Kitbook originally worked as a companion app, like all previous art does, but this created a lot of friction I didn't like. 
-	- I don't often take the time to start two dev servers and open two tabs. I often only worked in my Kitbook or only in my app, but not both which is the sweet spot. 
-	- Another friction point, is the work required to set up the component workbench with just the right scaffolding to match the main app. It's annoying to have to keep everything in sync (like i18n) for example. The layout structure above makes it easy to clearly specify what context is needed for components and what is app only. 
-	- This avoids all the compatibility issues other tools have around trying to use SvelteKit specific imports. 
-
-	Give the combined app and workbench approach a try and see if you like it. If you don't need the workbench published you can also easily add a script to remove the `kitbook` route folder before building for production.
-
-Let's move on to learn about Kitbook's [[2-viewer]] tool which bridges the gap between our app and our component workbench. 
+If you don't need the workbench published you can also easily add a script to remove the `kitbook` routes folder before building for production. *You could also [[1-use-by-itself-(for-a-library)|create an entirely separate SvelteKit app]] by itself and update the `importModuleGlobs` setting to point to the main app's folder, but then you lose the all the benefits of the [[2-viewer]] so I don't recommend that approach.*
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[4-roadmap]: 9-maintainer-notes/4-roadmap.md "Roadmap"
 [2-viewer]: 2-viewer.md "Viewer"
+[1-use-by-itself-(for-a-library)|create an entirely separate SvelteKit app]: 3-customizations/1-use-by-itself-(for-a-library).md "Use Kitbook by Itself"
 [//end]: # "Autogenerated link references"

packages/kitbook/src/docs/3-customizations/1-use-by-itself-(for-a-library).md

@@ -23,7 +23,7 @@ If you are using `svelte-package` and you don't want to add your stories and var
 
 ```
 *.variants.ts
-*.composition.svelte
+*.composition
 **/*.md
 *.svx
 ```

packages/kitbook/src/docs/4-component-compositions.md

@@ -10,6 +10,7 @@ There are no such things as `+page.svelte` or `+layout.svelte` compositions as t
 Now that you have a composition in place, learn how to [[5-write-documentation|document your components]], including sprinkling in compositions where helpful.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
+[SearchResult]: ../lib/layout/sidebar/search/SearchResult.md "SearchResult"
 [complex-examples]: 2-compositions/complex-examples.md "Advanced Composition Use Cases"
 [5-write-documentation|document your components]: 5-write-documentation.md "Write Documentation"
 [//end]: # "Autogenerated link references"

packages/kitbook/src/docs/6-easy-wikilinks.md

@@ -42,14 +42,12 @@ Sometimes when you link to a page in mid sentence like [[1-get-started|this proj
 
 [Foam](https://foambubble.github.io/foam/) supports [linking to specific sections](https://foambubble.github.io/foam/user/features/wikilinks#support-for-sections) of a page, which you can also take advantage of in Kitbook. So `[[6-easy-wikilinks#Setup Foam]]` would result in a direct link to the section above and looks like: [[6-easy-wikilinks#Setup Foam]]. If you change your section titles, Foam will not automatically update the link to that section though it will give you an editor warning on the wikilink that no section with such title exists.
 
+If you've made it this far, you must be a power user. Read on to add [[7-visual-regression-testing]].
 
----
-
-You've now learned the features of Kitbook as far as they have been documented. As you document and prototype your components for each situation you need, you may run into questions as to how to accomplish something. Feel free to browse the Kitbook related files in any of the provided [[8-examples|repo examples]] where Kitbook in is use. You may find your answer there. If not, please [create an issue](https://github.com/jacob-8/kitbook/issues/new), and let's discuss how you could add a needed feature.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [6-easy-wikilinks]: 6-easy-wikilinks.md "Easy Wikilinks"
 [1-get-started|this project's amazing guide to getting started]: 1-get-started.md "Get Started"
 [6-easy-wikilinks#Setup Foam]: 6-easy-wikilinks.md "Easy Wikilinks"
-[8-examples|repo examples]: 8-examples.md "Examples"
+[7-visual-regression-testing]: 7-visual-regression-testing.md "Visual Regression Testing"
 [//end]: # "Autogenerated link references"

packages/kitbook/src/docs/7-visual-regression-testing.md

@@ -0,0 +1,26 @@
+# Visual Regression Testing: In progress
+
+Beyond simply giving an easy way to mock components in a variety of states, the simple [[3-component-variants|Variants]] format of Kitbook enables easy visual regression testing of all your components using [Playwright](https://playwright.dev/). Here's how to set things up.
+
+## Install Playwright
+
+```bash
+npm install -D @playwright/test
+```
+
+## Add a custom Playwright config
+
+
+## Add GitHub Actions
+
+
+## Image cleanup
+
+---
+
+You've now learned the features of Kitbook as far as they have been documented. As you document and prototype your components for each situation you need, you may run into questions as to how to accomplish something. Feel free to browse the Kitbook related files in any of the provided [[8-examples|repo examples]] where Kitbook in is use. You may find your answer there. If not, please [create an issue](https://github.com/jacob-8/kitbook/issues/new), and let's discuss how you could add a needed feature.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[3-component-variants|Variants]: 3-component-variants.md "Component Variants"
+[8-examples|repo examples]: 8-examples.md "Examples"
+[//end]: # "Autogenerated link references"

packages/kitbook/src/docs/9-maintainer-notes/4-roadmap.md → packages/kitbook/src/docs/9-maintainer-notes/0-roadmap.md

@@ -1,9 +1,6 @@
 # Roadmap
 
-**This project is still in alpha and the API is still being shaped.**
-*(you have been warned, early-adopters)*
-
-## Alpha features I have already planned out and just need to implement - hold your horses
+## Remaining alpha features: I have already planned these out and just need to implement - just wait for them
 - visual regression testing
   - using Playwright but do note VitestPreview, [Histoire plugin](https://github.com/histoire-dev/histoire/tree/main/packages/histoire-plugin-screenshot) and [Viteshot](https://viteshot.com/)
 - auto-adjusting iframe height
@@ -12,7 +9,7 @@
   - compositions display in documentation when referenced, update the MDSvex to parse for links to compositions and just create an ID that can be targeted by composition
   - May need .not-prose when hoisted into documentation
 
-## Beta - please feel free to open issues and discuss what you may be able to contribute!
+## Beta: Please feel free to [create an issue](https://github.com/jacob-8/kitbook/issues/new) and discuss what you may be able to contribute!
 - responsive iframes shrink to keep interior resolution
 - movable viewer and adjustable shortcuts
 - show compositions in viewer
@@ -33,7 +30,7 @@
 - expand search to include raw string content with fuzzy search https://github.com/sveltejs/kit/blob/master/sites/kit.svelte.dev/src/lib/search/search.js
 - it's all focused on Typescript users, but someone could adjust things to make it work for a JavaScript only user
 
-## Rough edges to contribute - please ask how you can help
+## Rough edges: Please feel free to [create an issue](https://github.com/jacob-8/kitbook/issues/new) if you know how to help
 - catch when a variants file exists by itself and inform how to use variants
 - shouldn't crash upon finding oddly placed file like `/src/+layout.svelte` or `src/ind.md`
 - on build don't show folders that have no components with Kitbook files 
@@ -44,17 +41,17 @@
 - fix shiki-twoslash highlight not scrolling on small screens by learning from https://histoire.dev/guide/svelte3/controls.html
 
 ## Post 1.0
-- [admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
 - Dark mode (both for Kitbook and for individual sandboxes - or be able to show light and dark side by side) learn from https://github.com/dansvel/sveltekit-windi
-- backlinks/connections graph
+- [admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
+- backlinks/connections graph (see Foam examples)
 - display meta tags of iframe when rendering +page.svelte components
-- dynamic slots?
 - optional Stackblitz/Codeflow/Gitpod links? 
+- dynamic slots?
 
 ## Helpful Future Inspiration
 
+- Nuxt DevTools, Vue DevTools, [vite-plugin-devtools](https://github.com/pheno-agency/vite-plugin-devtools)
 - [KitDocs](https://kit-docs.svelteness.dev/) 
 - [svelte-knobby](https://github.com/Rich-Harris/svelte-knobby)
 - svelte-headlessui
 - https://github.com/importantimport/urara
-- Nuxt, Vue DevTools, https://github.com/pheno-agency/vite-plugin-devtools