svmarkdown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grtsinry43
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# svmarkdown (Svelte Markdown)
+
+Runtime-first Markdown rendering for Svelte.
+
+- Parser: `markdown-it`
+- Core output: custom AST/Blocks (not HTML strings)
+- Renderer: declarative Svelte component tree (no DOM scan/mount pipeline)
+
+[中文文档 (zh-CN)](./README.zh-CN.md)
+
+## Install
+
+```bash
+pnpm add svmarkdown
+```
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+  import { Markdown } from 'svmarkdown'
+  import Link from './Link.svelte'
+  import Image from './Image.svelte'
+  import Code from './Code.svelte'
+
+  let content = $state('Visit [Svelte](https://svelte.dev) and `inline code`')
+
+  const components = {
+    a: Link,
+    img: Image,
+    code: Code,
+  }
+</script>
+
+<Markdown {content} {components} />
+```
+
+## Custom Component Syntax
+
+### 1. Container (`:::`)
+
+just use ::: [component] key="value" to create a component block, and the content inside will be passed as `children` prop.
+
+```md
+::: Alert type=warning title="Heads up"
+This is **Markdown children**.
+:::
+```
+
+### 2. Fence (```)
+
+just use ```component:[component] {"key":"value"} to create a component block, and the content inside will be passed as `children` prop.
+
+````md
+```component:Chart {"title":"Traffic"}
+month,visits
+Jan,421
+Feb,530
+```
+````
+
+## API
+
+```ts
+import { Markdown, createParser, parseMarkdown } from 'svmarkdown'
+```
+
+- `parseMarkdown(markdown, options)`: parse once, returns `SvmdRoot`
+- `createParser(options)`: create a reusable parser for frequent updates
+- `<Markdown />`: runtime rendering with an `AST -> Svelte tree` update path
+
+## Parse Options
+
+```ts
+import type { SvmdParseOptions } from 'svmarkdown'
+
+const options: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: true,
+    Chart: {
+      container: false,
+      fence: true,
+      parseFenceBodyAsMarkdown: false,
+    },
+  },
+  fenceComponentPrefix: 'component:',
+}
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run test
+pnpm run build
+pnpm run play
+```
+
+## Advanced Extensions
+
+### Configure component blocks
+
+```ts
+const parseOptions: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: true,
+    Note: { container: true, fence: false },
+    Chart: { container: false, fence: true },
+    Card: { fence: true, parseFenceBodyAsMarkdown: true },
+  },
+}
+```
+
+### Custom props parsing
+
+```ts
+const parseOptions: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: {
+      parseProps(raw) {
+        if (!raw) return {}
+        if (raw.startsWith('yaml:')) {
+          return { source: raw.slice(5).trim() }
+        }
+        return { text: raw }
+      },
+    },
+  },
+}
+```
+
+### Custom fence prefix
+
+```ts
+const parseOptions: SvmdParseOptions = {
+  fenceComponentPrefix: '@component:',
+}
+```
+
+### Use markdown-it plugins
+
+```ts
+import footnote from 'markdown-it-footnote'
+import container from 'markdown-it-container'
+
+const parseOptions: SvmdParseOptions = {
+  markdownItPlugins: [
+    footnote,
+    [container, 'spoiler', { marker: ':' }],
+  ],
+}
+```
+
+### Provide your own MarkdownIt instance
+
+```ts
+import MarkdownIt from 'markdown-it'
+
+const md = new MarkdownIt({ html: true, linkify: true })
+const parseOptions: SvmdParseOptions = {
+  markdownIt: md,
+}
+```
+
+### Render raw HTML (unsafe)
+
+```svelte
+<Markdown
+  content={md}
+  parseOptions={{ markdownItOptions: { html: true } }}
+  renderOptions={{ allowDangerousHtml: true }}
+/>
+```
+
+### Control component inference
+
+```svelte
+<Markdown
+  content={md}
+  components={{ Alert, Chart }}
+  inferComponentBlocks={false}
+  parseOptions={{ componentBlocks: { Alert: true } }}
+/>
+```
+
+### Access component metadata
+
+```svelte
+<script lang="ts">
+  export let node
+  export let syntax
+  export let source
+</script>
+```
+
+### Render AST nodes directly
+
+```svelte
+<script lang="ts">
+  import { SvmdChildren, parseMarkdown } from 'svmarkdown'
+  const ast = parseMarkdown(md)
+</script>
+
+<SvmdChildren nodes={ast.children} components={components} />
+```
+
+## License
+
+MIT License

package/README.zh-CN.md

@@ -0,0 +1,208 @@
+# svmarkdown (Svelte Markdown)
+
+`svmarkdown` (Svelte Markdown) 是一个运行时 Markdown 渲染库：
+
+- 解析层：`markdown-it`
+- 输出格式：库自己的 AST/Blocks（非 HTML 字符串）
+- 渲染结果：声明式 Svelte 组件树
+
+## 安装
+
+```bash
+pnpm add svmarkdown
+```
+
+## 快速开始
+
+```svelte
+<script lang="ts">
+  import { Markdown } from 'svmarkdown'
+  import Link from './Link.svelte'
+  import Image from './Image.svelte'
+  import Code from './Code.svelte'
+
+  let content = $state('Visit [Svelte](https://svelte.dev) and `inline code`')
+
+  const components = {
+    a: Link,
+    img: Image,
+    code: Code,
+  }
+</script>
+
+<Markdown {content} {components} />
+```
+
+## 自定义组件语法
+
+### 1. Container（`:::`）
+
+你可以使用 ::: [组件名] key="value" 来创建一个组件块，块内的内容会作为 `children` prop 传入组件。
+
+```md
+::: Alert type=warning title="Heads up"
+这里是 **Markdown children**。
+:::
+```
+
+### 2. Fence（```）
+
+你可以使用 ```component:[组件名] {"key":"value"} 来创建一个组件块，块内的内容会作为 `children` prop 传入组件。
+
+````md
+```component:Chart {"title":"Traffic"}
+month,visits
+Jan,421
+Feb,530
+```
+````
+
+## API
+
+```ts
+import { Markdown, createParser, parseMarkdown } from 'svmarkdown'
+```
+
+- `parseMarkdown(markdown, options)`：一次性解析，返回 `SvmdRoot`
+- `createParser(options)`：创建可复用 parser，适合高频更新
+- `<Markdown />`：运行时渲染组件，每次变更时 `AST -> Svelte` 更新链路
+
+## parse options 定义
+
+```ts
+import type { SvmdParseOptions } from 'svmarkdown'
+
+const options: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: true,
+    Chart: {
+      container: false,
+      fence: true,
+      parseFenceBodyAsMarkdown: false,
+    },
+  },
+  fenceComponentPrefix: 'component:',
+}
+```
+
+## 开发
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run test
+pnpm run build
+pnpm run play
+```
+
+## 高级扩展用法
+
+### 更多组件块配置项
+
+```ts
+const options: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: true,
+    Note: { container: true, fence: false },
+    Chart: { container: false, fence: true },
+    Card: { fence: true, parseFenceBodyAsMarkdown: true },
+  },
+}
+```
+
+### 自定义 props 解析
+
+```ts
+const options: SvmdParseOptions = {
+  componentBlocks: {
+    Alert: {
+      parseProps(raw) {
+        if (!raw) return {}
+        if (raw.startsWith('yaml:')) {
+          return { source: raw.slice(5).trim() }
+        }
+        return { text: raw }
+      },
+    },
+  },
+}
+```
+
+### 自定义 fence 前缀
+
+```ts
+const options: SvmdParseOptions = {
+  fenceComponentPrefix: '@component:',
+}
+```
+
+### 使用 markdown-it 插件
+
+```ts
+import footnote from 'markdown-it-footnote'
+import container from 'markdown-it-container'
+
+const options: SvmdParseOptions = {
+  markdownItPlugins: [
+    footnote,
+    [container, 'spoiler', { marker: ':' }],
+  ],
+}
+```
+
+### 传入自定义 MarkdownIt 实例
+
+```ts
+import MarkdownIt from 'markdown-it'
+
+const md = new MarkdownIt({ html: true, linkify: true })
+const options: SvmdParseOptions = {
+  markdownIt: md,
+}
+```
+
+### 渲染原始 HTML（不安全）
+
+```svelte
+<Markdown
+  content={md}
+  parseOptions={{ markdownItOptions: { html: true } }}
+  renderOptions={{ allowDangerousHtml: true }}
+/>
+```
+
+### 关闭组件块自动推断
+
+```svelte
+<Markdown
+  content={md}
+  components={{ Alert, Chart }}
+  inferComponentBlocks={false}
+  parseOptions={{ componentBlocks: { Alert: true } }}
+/>
+```
+
+### 读取组件元信息
+
+```svelte
+<script lang="ts">
+  export let node
+  export let syntax
+  export let source
+</script>
+```
+
+### 直接渲染 AST 节点
+
+```svelte
+<script lang="ts">
+  import { SvmdChildren, parseMarkdown } from 'svmarkdown'
+  const ast = parseMarkdown(md)
+</script>
+
+<SvmdChildren nodes={ast.children} components={components} />
+```
+
+## License
+
+MIT License

package/dist/Markdown.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { SvmdComponentMap, SvmdParseOptions, SvmdRenderOptions } from './types';
+interface Props {
+    content: string;
+    components?: SvmdComponentMap;
+    parseOptions?: SvmdParseOptions;
+    renderOptions?: SvmdRenderOptions;
+    inferComponentBlocks?: boolean;
+}
+declare const Markdown: import("svelte").Component<Props, {}, "">;
+type Markdown = ReturnType<typeof Markdown>;
+export default Markdown;