svelte-readme 3.6.3 → 4.0.0

package/README.md

@@ -1,10 +1,10 @@
 # svelte-readme
 
-> Develop and demo your Svelte components in your README.md.
+> A Vite plugin and Svelte preprocessor for developing and demoing your Svelte components in your README.md.
 
 ## Readme Driven Development
 
-This project embraces the concept of [Readme Driven Development](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) (RDD) – or more generally, documentation driven development.
+This project embraces the concept of [Readme Driven Development](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) (RDD), or more generally, documentation driven development.
 
 This module enables the `README.md` to be used for:
 
@@ -24,24 +24,23 @@ At its core, this library is a simple Svelte preprocessor.
 1. Use the `svelte` entry defined in your project `package.json`
 2. Use `README.md` as the Svelte source code
 3. Parse Markdown using [Markdown It](https://github.com/markdown-it/markdown-it)
-4. Run code within `svelte` code fence blocks so that demos are juxtaposed with code
+4. Highlight code with a built-in highlighter (`svelte`, `typescript`/`javascript`, `json`, `yaml`, `bash`) and run `svelte` code fence blocks so that demos are juxtaposed with code
+5. Style the result with [GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css) to maintain a consistent look with [github.com](https://github.com/)
 
-[GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css) is used for styling to maintain a consistent style with [github.com](https://github.com/).
+## Installation
 
-### Libraries
-
-- [Markdown It](https://github.com/markdown-it/markdown-it)
-- [PrismJS](https://github.com/PrismJS/prism)
-- [GitHub Markdown CSS](https://github.com/sindresorhus/github-markdown-css)
+```sh
+npm install svelte-readme
+```
 
 ## Usage
 
 This library exports two methods:
 
-- `createConfig` (default export): creates a Rollup InputOptions object for you
+- `svelteReadme`: creates a Vite plugin for you
 - `preprocessReadme`: standalone Svelte markup preprocessor
 
-`createConfig` is tightly coupled with Rollup. At a minimum, `package.json#svelte` and `package.json#name` are required.
+`svelteReadme` requires Svelte 5+ as a peer dependency. `preprocessReadme` has no such constraint. At a minimum, `package.json#svelte` and `package.json#name` are required.
 
 **package.json**
 
@@ -49,119 +48,88 @@ This library exports two methods:
 {
   "name": "my-svelte-component",
   "svelte": "./src/index.js",
-  "main": "./lib/index.js",
-  "module": "./lib/index.mjs",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
   "scripts": {
-    "dev": "rollup -cw",
-    "build": "rollup -c",
-    "prepack": "BUNDLE=true rollup -c"
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
   },
   "homepage": "https://github.com/metonym/svelte-readme"
 }
 ```
 
-**rollup.config.js**
-
-The default export from "svelte-readme" will create a Rollup configuration used to develop and generate the demo.
-
-```js
-import resolve from "@rollup/plugin-node-resolve";
-import svelte from "rollup-plugin-svelte";
-import svelteReadme from "svelte-readme";
-import pkg from "./package.json";
-
-export default () => {
-  if (process.env.BUNDLE !== "true") {
-    return svelteReadme();
-  }
-
-  return ["es", "umd"].map((format) => {
-    const UMD = format === "umd";
-
-    return {
-      input: pkg.svelte,
-      output: {
-        format,
-        file: UMD ? pkg.main : pkg.module,
-        name: UMD ? pkg.name : undefined,
-      },
-      plugins: [svelte(), resolve()],
-    };
-  });
-};
-```
+**vite.config.ts**
 
-### API
+`svelteReadme` is a standard Vite plugin factory: it returns `Plugin[]`, so it composes with the rest of your Vite config instead of replacing it.
 
 ```ts
-interface CreateConfigOptions {
-  /**
-   * set to `true` to minify the HTML/JS
-   * @default false
-   */
-  minify: boolean;
+import { svelteReadme } from "svelte-readme";
+import { defineConfig } from "vite";
 
+export default defineConfig({
+  plugins: [svelteReadme()],
+  server: { port: 3000 }, // passes through untouched
+});
+```
+
+## API
+
+All properties are optional.
+
+> [!NOTE]
+> `svelteReadme` owns `build.outDir` (set via the `outDir` option below, not `build.outDir`) and `build.rollupOptions.input`/`appType`. If you set your own `build.rollupOptions` in `vite.config.ts`, the outcome depends on Vite's plugin `config` hook merge order — this is composable for fields `svelteReadme` doesn't touch, but not fully composable for the fields it does.
+
+```ts
+interface SvelteReadmeOptions {
   /**
    * set the folder to emit the files
    * @default "dist"
    */
-  outDir: string;
+  outDir?: string;
 
   /**
    * custom CSS appended to the <style> block
    * @default ""
    */
-  style: string;
+  style?: string;
 
   /**
    * set to `true` to omit the default GitHub styles
    * @default false
    */
-  disableDefaultCSS: boolean;
+  disableDefaultCSS?: boolean;
 
   /**
    * value to prepend to relative URLs (i.e. GitHub repo URL)
    * @default undefined
    */
-  prefixUrl: string;
+  prefixUrl?: string;
 
   /**
-   * `rollup-plugin-svelte` options
-   * @default {}
+   * Called with the source of each `svelte` code fence before it's highlighted for display,
+   * so it can be pretty-printed with your own formatter (e.g. Prettier). The code fence is
+   * displayed unformatted if this is omitted or its result rejects/throws.
+   * @default undefined
    */
-  svelte: RollupPluginSvelteOptions;
+  format?: (source: string) => string | Promise<string>;
 
   /**
-   * Rollup plugins
-   * @default {[]}
+   * `@sveltejs/vite-plugin-svelte` options
+   * @default {}
    */
-  plugins: Plugin[];
+  svelte?: VitePluginSvelteOptions;
 
   /**
-   * Rollup output options
-   * @default {{}}
+   * Append content to the `head` element in `index.html`
+   * @default undefined
    */
-  output: OutputOptions;
+  head?: string;
 }
 ```
 
-## Limitations
-
-### Comments in script blocks
-
-Single line comments in Svelte script blocks are not supported.
-
-Use multi-line comments instead.
-
-```diff
-- let toggled; // comment
-+ let toggled; /** comment */
-```
-
-## Prior art
-
-This project is inspired by [MDsveX](https://github.com/pngwn/mdsvex).
-
 ## Changelog
 
 [CHANGELOG.md](CHANGELOG.md)

package/dist/button.css

@@ -0,0 +1,28 @@
+/**
+ * GitHub Primer button CSS
+ * https://primer.style/css/components/buttons
+ **/
+.code-fence button {
+  font-family: inherit;
+  text-transform: none;
+  position: relative;
+  display: inline-block;
+  padding: 5px 16px;
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 20px;
+  white-space: nowrap;
+  vertical-align: middle;
+  cursor: pointer;
+  user-select: none;
+  border: 1px solid;
+  border-radius: 6px;
+  appearance: none;
+  color: #24292e;
+  background-color: #fafbfc;
+  border-color: rgba(27, 31, 35, 0.15);
+  box-shadow:
+    0 1px 0 rgba(27, 31, 35, 0.04),
+    inset 0 1px 0 rgba(255, 255, 255, 0.25);
+  transition: background-color 0.2s cubic-bezier(0.3, 0, 0.5, 1);
+}

package/dist/highlight/bash.d.ts

@@ -0,0 +1,2 @@
+export declare const styles = "";
+export declare function highlightBash(source: string): string;

package/dist/highlight/json.d.ts

@@ -0,0 +1,2 @@
+export declare const styles = "";
+export declare function highlightJson(source: string): string;

package/dist/highlight/shared.d.ts

@@ -0,0 +1,11 @@
+export type Claim = {
+    start: number;
+    end: number;
+    className: string;
+};
+export type GapFill = (text: string) => string;
+export declare function escapeHtml(text: string): string;
+export declare function token(className: string, text: string): string;
+export declare const baseTokenStyles: string;
+export declare function renderClaims(source: string, claims: Claim[], gapFill: GapFill): string;
+export declare function gapFill(text: string): string;

package/dist/highlight/svelte.d.ts

@@ -0,0 +1,2 @@
+export declare const styles: string;
+export declare function highlightSvelte(source: string): string;

package/dist/highlight/typescript.d.ts

@@ -0,0 +1,5 @@
+import { type Claim } from "./shared.js";
+export declare const styles: string;
+export declare function codeGapFill(text: string): string;
+export declare function collectLeafClaims(root: any, offset: number): Claim[];
+export declare function highlightTypeScript(source: string): string;

package/dist/highlight/yaml.d.ts

@@ -0,0 +1,2 @@
+export declare const styles: string;
+export declare function highlightYaml(source: string): string;

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { preprocessReadme } from "./preprocessReadme";
-export { default } from "./createConfig";
+export { preprocessReadme } from "./preprocessReadme.js";
+export { svelteReadme } from "./svelteReadme.js";