Doc website scaffolding + fixes

Fixes: quarto preview, svelte files in subfolders, CSS

Author: jimjam-slam

.github/workflows/_publish.yml

@@ -0,0 +1,33 @@
+on:
+  workflow_dispatch:
+  push:
+    branches: main
+
+name: Quarto Publish
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Install npm
+        uses: actions/setup-node@v3
+
+      - name: Install npm packages
+        run: npm install
+        working-directory: ./docs
+
+      - name: Render and Publish
+        uses: quarto-dev/quarto-actions/publish@v2
+        path: docs
+        with:
+          target: gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -14,3 +14,8 @@
 
 # lua
 /.luarc.json
+
+# rendered documentation site
+/docs/_site/
+/docs/.quarto/
+/docs/.sverto/

README.md

@@ -1,7 +1,12 @@
 # sverto
-Add Svelte visualisations to your Quarto documents
 
-## 🛍 Prerequisites
+**Sverto** is an extension for [Quarto](https://quarto.org) that lets you seamlessly write and include [Svelte](https://svelte.dev) components, like charts and other visuals, in your Quarto website.
+
+Your Svelte components can seamlessly react to your ObservableJS code, making it quick and easy to build visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
+
+## 📋 Prerequisites
+
+You'll need to install two things to run Sverto:
 
 - [Quarto](https://quarto.org)
 - [Node and the Node Package Manager (npm)](https://nodejs.org)
@@ -11,18 +16,18 @@ Add Svelte visualisations to your Quarto documents
 Install the project extension using:
 
 ```
-quarto use template 360-info/sverto@firstrelease
+quarto use template 360-info/sverto@firstrelease-docs
 ```
 
-This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
-
 Then run:
 
 ```
 npm install
 ```
 
-This will install everything you need for your Svelte components to work to the `node_modules` folder. You won't need to touch this folder, and it doesn't need to go into version control. It'll also create a `package-lock.json`, which you _should_ version control.
+This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
+
+> **Note:** Sverto depends on running [project pre-render scripts](https://quarto.org/docs/projects/scripts.html#pre-and-post-render), so you can't currently use it with single documents.
 
 ## 🎉 Use
 
@@ -37,10 +42,10 @@ Here's the short way to add Svelte component you've written to a Quarto doc:
     ```
 
 2. Import your Svelte component with `Component = import_svelte("Component.svelte")`
-3. Add a target block for your visual and give it an `#id`
+3. Add a target block for your visual using `:::` and give it an `#id`
 4. Instantiate the Svelte component with `myVisual = Component.default()` using some default props and your target block
 5. Update the instantiated component with `myVisual.propName`
-6. Render your Quarto project as usual with `quarto render` or `quarto preview`.
+6. Render your Quarto website as usual with `quarto render` or `quarto preview`.
 
 **To see this all in practice, check out [`example.qmd`](./example.qmd).**
 
@@ -71,4 +76,4 @@ If you'd prefer to compile your own Svelte components instead of letting this ex
 
 If you have any problems with the extension, please feel free to [create an issue](https://github.com/360-info/sverto)!
 
-Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and guidance in designing Sverto!
+Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and guidance getting Sverto working!

_extensions/sverto/create-imports.lua

@@ -66,24 +66,22 @@ local preprocess_qmd_filter = {
         "import%_svelte%(\"([%w;,/%?:@&=%+%$%-_%.!~%*'%(%)#]+)%.svelte\"%)"
 
       local block_text = block.text
-    
-      print(">>> OJS block found...")
-      print(block_text)
+
+      -- get the qmd_path from disk
+      local current_qmd_path = read_file(".sverto/.sverto-current-qmd-folder")
 
       -- first, extract .svelte paths in import_svelte() statements
       for svelte_path in block_text:gmatch(svelte_import_syntax) do
-        print("Svelte file found...")
-        print(svelte_path)
-        -- table.insert(svelte_files, svelte_path .. ".svelte")
-        append_to_file(".sverto/.sverto-imports", svelte_path .. ".svelte\n")
+        append_to_file(".sverto/.sverto-imports",
+          current_qmd_path .. svelte_path .. ".svelte\n")
       end
 
       -- now change `import_svelte("X.svelte")` refs to `import("X.js")`
       -- TODO - neaten up relative paths instead of assuming we're going from
       -- /site_libs/quarto-ojs
       block.text = block_text:gsub(
         svelte_import_syntax,
-        "import(\"./../../%1.js\");")
+        "import(\"./../../" .. current_qmd_path .. "%1.js\");")
 
     end
     return block
@@ -117,20 +115,16 @@ end
 -- (write the identified .svelte files out to a file too!)
 for key, qmd_path in ipairs(in_files) do
 
-  -- print(">>> CREATING IMPORT FOR " .. qmd_path)
   local doc = pandoc.read(read_file(qmd_path))
+
+  -- store the current qmd_path on disk so the filter can access it
+  write_file(".sverto/.sverto-current-qmd-folder", path_dir(qmd_path))
 
   -- pre-process the qmd, populating `svelte_files` in the process
   -- local svelte_files = {}
   local transformed_doc = doc:walk(preprocess_qmd_filter)
   create_dir_recursively(".sverto/" .. path_dir(qmd_path))
   write_file(".sverto/" .. qmd_path, pandoc.write(transformed_doc, "markdown"))
-
-  -- write the svelte_files out to .sverto-imports
-  -- svelte_file_text = table.concat(svelte_files, "\n")
-  -- print("Saving Svelte imports:")
-  -- print(svelte_file_text)
-  -- write_file(".sverto/.sverto-imports", svelte_file_text)
 
 end
 

_extensions/sverto/refresh.ts

@@ -1,6 +1,10 @@
 // delete the temporary import block files and the temp render metadata
-try {
-  await Deno.remove(".sverto/",  { recursive: true })
-} catch {
 
+if (Deno.env.get("QUARTO_PROJECT_RENDER_ALL") == "1") {
+  try {
+    await Deno.remove(".sverto/",  { recursive: true })
+  } catch {
+  
+  }
 }
+

_extensions/sverto/rollup.config.js

@@ -1,42 +1,17 @@
 import svelte from 'rollup-plugin-svelte';
 import commonjs from '@rollup/plugin-commonjs';
 import resolve from '@rollup/plugin-node-resolve';
-// import livereload from 'rollup-plugin-livereload';
 import { terser } from 'rollup-plugin-terser';
-import css from 'rollup-plugin-css-only';
 
 const fs = require('fs');
 const path = require('node:path');
 
 // this is false when we run rollup with -w/--watch (never presently)
 const production = !process.env.ROLLUP_WATCH;
 
-// function serve() {
-// 	let server;
-
-// 	function toExit() {
-// 		if (server) server.kill(0);
-// 	}	
-
-// 	return {
-// 		writeBundle() {
-// 			if (server) return;
-// 			server = require('child_process').spawn('npm', ['run', 'start', '--', '--dev'], {
-// 				stdio: ['ignore', 'inherit', 'inherit'],
-// 				shell: true
-// 			});
-
-// 			process.on('SIGTERM', toExit);
-// 			process.on('exit', toExit);
-// 		}
-// 	};
-// }
-
 // get quarto project output directory and list of inputs
-// const quartoOutDir = process.env.QUARTO_PROJECT_OUTPUT_DIR;
 const quartoOutDir = fs.readFileSync('.sverto/.sverto-outdir', 'utf8');
 
-let svelteConfig = {};
 const svelteImportListPath = '.sverto/.sverto-imports';
 
 // skip svelte compilation if there's nothing to compile
@@ -64,27 +39,19 @@ export default uniqueSvelteFiles.map(
 		},
 		plugins: [
 			svelte({
+				// css is added to the js bundle instead
+				emitCss: false,
 				compilerOptions: {
+					// required for ojs reactivity
 					accessors: true,
 					dev: !production,
 				}
 			}),
-			css({
-				output: path.join(
-					quartoOutDir,
-					path.dirname(svelteFile),
-					path.basename(svelteFile, ".svelte") + ".css")
-			}),
 			resolve({
 				browser: true,
 				dedupe: ["svelte"]
 			}),
 			commonjs(),
-			// !production && serve(),
-			// !production && livereload("public"),
 			production && terser()
-		]//,
-		// watch: {
-		// 	clearScreen: false
-		// }
+		]
 	}));

docs/.gitignore

@@ -0,0 +1,4 @@
+/.quarto/
+
+/node_modules/
+/.sverto/

docs/_extensions/sverto/_extension.yml

@@ -0,0 +1,20 @@
+title: Sverto
+author: 360info
+version: 0.0.1
+quarto-version: ">=1.2.0"
+contributes:
+  project:
+    project:
+      type: website
+      pre-render:
+        - refresh.ts
+        - create-imports.lua
+        - compile-imports.ts
+    format: sverto-html
+  formats:
+    html:
+      filters:
+        - cleanup-transform.lua
+    revealjs:
+      filters:
+        - cleanup-transform.lua

docs/_extensions/sverto/cleanup-transform.lua

@@ -0,0 +1,6 @@
+-- replaces the doc body with just its first block (assumed to be the
+-- version of the doc with transformed .svelte -> .js refs)
+Pandoc = function(doc)
+  doc.blocks = doc.blocks[1].content
+  return doc
+end

docs/_extensions/sverto/compile-imports.ts

@@ -0,0 +1,13 @@
+// check if _extensions/svero exists or _extensions/360-info/sverto
+
+import * as path from "https://deno.land/std/path/mod.ts";
+
+const thisScript = path.fromFileUrl(import.meta.url);
+const rollupConfig = path.join(path.dirname(thisScript), "rollup.config.js");
+
+// call rollup with the config file
+const cmd = ["npm", "run", "build", rollupConfig];
+const compileStep = Deno.run({ cmd });
+await compileStep.status();
+
+// console.log("Svelte compilation + bundling done!");