@aureuma/svelta 0.2.0 → 0.4.1

package/README.md

@@ -33,6 +33,50 @@ Set `PUBLIC_SVELTA_EXPERIENCE=docs` or `PUBLIC_SVELTA_EXPERIENCE=blog`.
 npm run dev
 ```
 
+## Pattern-First Configuration
+
+Configure docs and blog experiences through explicit pattern builders:
+
+```ts
+import { createSveltaPatternConfig } from '@aureuma/svelta/experience';
+
+const patterns = createSveltaPatternConfig({
+	docs: {
+		brandName: 'Aureuma',
+		productName: 'Documentation',
+		search: { placeholder: 'Search docs...', shortcut: 'Ctrl K' },
+		editLinkTemplate: 'https://github.com/Aureuma/aureuma/blob/main/src/content/docs/:slug.md'
+	},
+	blog: {
+		pageSize: 8,
+		maxPageSize: 24,
+		infiniteScroll: true,
+		showRss: true
+	}
+});
+```
+
+This keeps the implementation reusable while app repos control behavior through config.
+
+## Raw Docs Runtime (No mdsvex Required)
+
+If your app stores docs as plain markdown and wants server-rendered HTML without mdsvex, use `createRawDocs`:
+
+```ts
+import { createRawDocs } from '@aureuma/svelta/server';
+
+const docs = createRawDocs({
+	rawModules: import.meta.glob('/src/content/docs/*.md', {
+		query: '?raw',
+		import: 'default'
+	}),
+	renderMarkdown: async (markdown) => yourMarkdownRenderer(markdown)
+});
+
+export const getDocsSidebar = docs.getSidebar;
+export const getDocsPageBySlug = docs.getPageBySlug;
+```
+
 ## Internal Hosting (Pre-deploy)
 
 ```sh

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@aureuma/svelta",
 	"private": false,
-	"version": "0.2.0",
+	"version": "0.4.1",
 	"type": "module",
 	"files": [
 		"packages/core/dist",
@@ -42,14 +42,16 @@
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build",
+		"build:core": "npm -w @aureuma/svelta-core run build",
 		"preview": "vite preview",
 		"host:internal": "npm run build && npm run preview -- --host 0.0.0.0 --port 4173",
 		"prepare": "svelte-kit sync || echo ''",
-		"postinstall": "npm -w @aureuma/svelta-core run build",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-		"test:e2e": "playwright test",
-		"test": "npm run check && npm run test:e2e",
+		"test:guard": "node scripts/ensure-ci.mjs",
+		"test:server": "npm run test:guard && npm run build:core && node --test tests/raw-docs.test.mjs",
+		"test:e2e": "npm run test:guard && playwright test",
+		"test": "npm run test:guard && npm run check && npm run test:server && npm run test:e2e",
 		"changeset": "changeset",
 		"version-packages": "changeset version",
 		"release": "changeset publish",

package/packages/core/dist/experience/index.d.ts

@@ -1,5 +1,7 @@
 import type { ExperienceCatalog, ExperienceDefinition, ExperienceKind } from '../types/experience';
-export type { ExperienceCatalog, ExperienceDefinition, ExperienceKind } from '../types/experience';
+import { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './patterns';
+export type { ExperienceCatalog, ExperienceDefinition, ExperienceKind, SveltaBlogPatternConfig, SveltaDocsPatternConfig, SveltaNavItem, SveltaPatternConfig } from '../types/experience';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl };
 export declare function parseExperienceKind(input: string | null | undefined, fallback?: ExperienceKind): ExperienceKind;
 export declare function createExperienceCatalog(opts?: {
     defaultKind?: ExperienceKind;

package/packages/core/dist/experience/index.js

@@ -1,3 +1,5 @@
+import { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './patterns';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl };
 const DEFAULTS = {
     docs: {
         kind: 'docs',

package/packages/core/dist/experience/patterns.d.ts

@@ -0,0 +1,26 @@
+import type { SveltaBlogPatternConfig, SveltaDocsPatternConfig, SveltaPatternConfig } from '../types/experience';
+type DocsPatternOverrides = Partial<Omit<SveltaDocsPatternConfig, 'kind' | 'navigation' | 'search' | 'toc' | 'feedback'>> & {
+    navigation?: Partial<SveltaDocsPatternConfig['navigation']> & {
+        header?: SveltaDocsPatternConfig['navigation']['header'];
+        footer?: SveltaDocsPatternConfig['navigation']['footer'];
+    };
+    search?: Partial<SveltaDocsPatternConfig['search']>;
+    toc?: Partial<SveltaDocsPatternConfig['toc']>;
+    feedback?: Partial<SveltaDocsPatternConfig['feedback']>;
+};
+type BlogPatternOverrides = Partial<Omit<SveltaBlogPatternConfig, 'kind' | 'navigation'>> & {
+    navigation?: Partial<SveltaBlogPatternConfig['navigation']> & {
+        header?: SveltaBlogPatternConfig['navigation']['header'];
+        footer?: SveltaBlogPatternConfig['navigation']['footer'];
+    };
+};
+export declare const DEFAULT_DOCS_PATTERN_CONFIG: SveltaDocsPatternConfig;
+export declare const DEFAULT_BLOG_PATTERN_CONFIG: SveltaBlogPatternConfig;
+export declare function createDocsPatternConfig(overrides?: DocsPatternOverrides): SveltaDocsPatternConfig;
+export declare function createBlogPatternConfig(overrides?: BlogPatternOverrides): SveltaBlogPatternConfig;
+export declare function createSveltaPatternConfig(overrides?: {
+    docs?: DocsPatternOverrides;
+    blog?: BlogPatternOverrides;
+}): SveltaPatternConfig;
+export declare function resolveDocsEditUrl(config: SveltaDocsPatternConfig, slug: string): string;
+export {};

package/packages/core/dist/experience/patterns.js

@@ -0,0 +1,96 @@
+export const DEFAULT_DOCS_PATTERN_CONFIG = {
+    kind: 'docs',
+    brandName: 'svelta',
+    productName: 'Documentation',
+    title: 'Structured docs with first-class markdown ergonomics.',
+    description: 'Ship Mintlify-style docs UX with sectioned navigation, command-palette search, right-rail table of contents, and content feedback loops.',
+    defaultSectionLabel: 'Guides',
+    sectionOrder: ['overview', 'getting-started', 'guides', 'api', 'reference'],
+    navigation: {
+        header: [
+            { label: 'Docs', href: '/docs' },
+            { label: 'Blog', href: '/blog' }
+        ],
+        footer: [
+            { label: 'Overview', href: '/docs/overview' },
+            { label: 'Getting Started', href: '/docs/getting-started' }
+        ]
+    },
+    search: {
+        enabled: true,
+        placeholder: 'Search documentation...',
+        shortcut: 'Ctrl K'
+    },
+    toc: {
+        enabled: true,
+        title: 'On This Page'
+    },
+    feedback: {
+        enabled: true,
+        prompt: 'Was this page helpful?'
+    },
+    editLinkTemplate: 'https://github.com/Aureuma/svelta/blob/main/src/content/docs/:slug.md'
+};
+export const DEFAULT_BLOG_PATTERN_CONFIG = {
+    kind: 'blog',
+    brandName: 'svelta',
+    title: 'Editorial publishing with modern feed ergonomics.',
+    description: 'Publish markdown-driven updates with in-feed tag filtering, continuous infinite loading, author attribution, and RSS delivery.',
+    pageSize: 8,
+    maxPageSize: 24,
+    showRss: true,
+    navigation: {
+        header: [
+            { label: 'Blog', href: '/blog' },
+            { label: 'Archive', href: '/blog/archive' }
+        ],
+        footer: [
+            { label: 'All posts', href: '/blog' },
+            { label: 'Authors', href: '/blog/authors' },
+            { label: 'RSS', href: '/feed.xml' }
+        ]
+    }
+};
+export function createDocsPatternConfig(overrides) {
+    return {
+        ...DEFAULT_DOCS_PATTERN_CONFIG,
+        ...overrides,
+        kind: 'docs',
+        navigation: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.navigation,
+            ...(overrides?.navigation ?? {})
+        },
+        search: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.search,
+            ...(overrides?.search ?? {})
+        },
+        toc: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.toc,
+            ...(overrides?.toc ?? {})
+        },
+        feedback: {
+            ...DEFAULT_DOCS_PATTERN_CONFIG.feedback,
+            ...(overrides?.feedback ?? {})
+        }
+    };
+}
+export function createBlogPatternConfig(overrides) {
+    return {
+        ...DEFAULT_BLOG_PATTERN_CONFIG,
+        ...overrides,
+        kind: 'blog',
+        navigation: {
+            ...DEFAULT_BLOG_PATTERN_CONFIG.navigation,
+            ...(overrides?.navigation ?? {})
+        }
+    };
+}
+export function createSveltaPatternConfig(overrides) {
+    return {
+        docs: createDocsPatternConfig(overrides?.docs),
+        blog: createBlogPatternConfig(overrides?.blog)
+    };
+}
+export function resolveDocsEditUrl(config, slug) {
+    return config.editLinkTemplate.replaceAll(':slug', slug);
+}

package/packages/core/dist/index.d.ts

@@ -13,6 +13,8 @@ export { default as DocsSectionGrid } from './components/docs/DocsSectionGrid.sv
 export { default as DocsShell } from './components/docs/DocsShell.svelte';
 export { default as DocsSidebar } from './components/docs/DocsSidebar.svelte';
 export { createExperienceCatalog, parseExperienceKind } from './experience';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './experience';
 export type { BlogAuthor, BlogAuthorSummary, BlogArchiveGroup, BlogCategory, BlogPost, BlogPostFull, BlogPostWithContent, BlogTag, SharePlatform } from './types/blog';
 export type { DocsPage, DocsPageFull, DocsPageWithContent, DocsSection, DocsSidebarSection } from './types/docs';
 export type { ExperienceCatalog, ExperienceDefinition, ExperienceKind } from './types/experience';
+export type { SveltaBlogPatternConfig, SveltaDocsPatternConfig, SveltaNavItem, SveltaPatternConfig } from './types/experience';

package/packages/core/dist/index.js

@@ -14,3 +14,4 @@ export { default as DocsSectionGrid } from './components/docs/DocsSectionGrid.sv
 export { default as DocsShell } from './components/docs/DocsShell.svelte';
 export { default as DocsSidebar } from './components/docs/DocsSidebar.svelte';
 export { createExperienceCatalog, parseExperienceKind } from './experience';
+export { createBlogPatternConfig, createDocsPatternConfig, createSveltaPatternConfig, DEFAULT_BLOG_PATTERN_CONFIG, DEFAULT_DOCS_PATTERN_CONFIG, resolveDocsEditUrl } from './experience';

package/packages/core/dist/server/docs.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { DocsPage, DocsPageFull, DocsSidebarSection, DocsSection } from '../types/docs';
+import type { DocsPage, DocsPageFull, DocsPageWithContent, DocsSidebarSection, DocsSection } from '../types/docs';
 declare const docsFrontmatterSchema: z.ZodObject<{
     title: z.ZodString;
     navTitle: z.ZodOptional<z.ZodString>;
@@ -29,6 +29,14 @@ export type DocsCreateConfig = {
     sectionOrder?: string[];
     mapFrontmatter?: DocsFrontmatterAdapter;
 };
+export type DocsMarkdownRenderer = (markdown: string) => string | Promise<string>;
+export type RawDocsCreateConfig = {
+    rawModules: Record<string, () => Promise<string>>;
+    defaultSectionLabel?: string;
+    sectionOrder?: string[];
+    mapFrontmatter?: DocsFrontmatterAdapter;
+    renderMarkdown?: DocsMarkdownRenderer;
+};
 export declare function createDocs(config: DocsCreateConfig): {
     getAllPages: () => Promise<DocsPage[]>;
     getAllPagesFull: () => Promise<DocsPageFull[]>;
@@ -41,4 +49,16 @@ export declare function createDocs(config: DocsCreateConfig): {
     }>;
     pickLandingPage: () => Promise<DocsPage | null>;
 };
+export declare function createRawDocs(config: RawDocsCreateConfig): {
+    getAllPages: () => Promise<DocsPage[]>;
+    getAllPagesWithContent: () => Promise<DocsPageWithContent[]>;
+    getPageBySlug: (slug: string) => Promise<DocsPageWithContent | null>;
+    getSections: () => Promise<DocsSection[]>;
+    getSidebar: () => Promise<DocsSidebarSection[]>;
+    getAdjacentPages: (slug: string) => Promise<{
+        previous: DocsPage | null;
+        next: DocsPage | null;
+    }>;
+    pickLandingPage: () => Promise<DocsPage | null>;
+};
 export {};

package/packages/core/dist/server/docs.js

@@ -1,5 +1,6 @@
 import { DEV } from 'esm-env';
 import matter from 'gray-matter';
+import { marked } from 'marked';
 import { z } from 'zod';
 const docsFrontmatterSchema = z.object({
     title: z.string(),
@@ -191,3 +192,118 @@ export function createDocs(config) {
         pickLandingPage
     };
 }
+const defaultRenderMarkdown = (markdown) => String(marked.parse(markdown));
+export function createRawDocs(config) {
+    const defaultSectionLabel = config.defaultSectionLabel ?? 'Guides';
+    const sectionOrder = config.sectionOrder ?? ['overview', 'getting-started', 'guides', 'api', 'reference'];
+    const renderMarkdown = config.renderMarkdown ?? defaultRenderMarkdown;
+    let cachedContentIndex = null;
+    async function buildContentIndex() {
+        if (!DEV && cachedContentIndex)
+            return cachedContentIndex;
+        const pages = [];
+        const paths = Object.keys(config.rawModules).sort();
+        for (const path of paths) {
+            const file = path.split('/').pop();
+            const slug = file?.replace(/\.md(?:\?.*)?$/, '');
+            if (!slug)
+                continue;
+            const rawFn = config.rawModules[path];
+            if (!rawFn)
+                continue;
+            const raw = await rawFn();
+            const { data, content } = matter(raw);
+            const meta = config.mapFrontmatter
+                ? config.mapFrontmatter({ data, content, slug, path })
+                : docsFrontmatterSchema.parse(data);
+            if (meta.draft)
+                continue;
+            const section = sectionFromMeta(meta, defaultSectionLabel, sectionOrder);
+            const updated = parseUpdatedAt(meta.updatedAt);
+            const html = await renderMarkdown(content);
+            pages.push({
+                slug,
+                title: meta.title.trim(),
+                navTitle: (meta.navTitle || meta.title).trim(),
+                description: (meta.description || '').trim(),
+                section,
+                order: meta.order ?? 1000,
+                tags: meta.tags ?? [],
+                updatedAt: updated.iso,
+                updatedAtLong: updated.long,
+                html,
+                raw: content,
+                frontmatter: typeof data === 'object' && data ? data : {}
+            });
+        }
+        pages.sort((a, b) => {
+            if (a.section.order !== b.section.order)
+                return a.section.order - b.section.order;
+            if (a.section.id !== b.section.id)
+                return a.section.id.localeCompare(b.section.id);
+            if (a.order !== b.order)
+                return a.order - b.order;
+            return a.title.localeCompare(b.title);
+        });
+        if (!DEV)
+            cachedContentIndex = pages;
+        return pages;
+    }
+    function stripContent(page) {
+        const { html: _html, raw: _raw, frontmatter: _frontmatter, ...meta } = page;
+        return meta;
+    }
+    async function getAllPages() {
+        const pages = await buildContentIndex();
+        return pages.map(stripContent);
+    }
+    async function getAllPagesWithContent() {
+        return buildContentIndex();
+    }
+    async function getPageBySlug(slug) {
+        const pages = await buildContentIndex();
+        return pages.find((page) => page.slug === slug) ?? null;
+    }
+    async function getSections() {
+        const pages = await getAllPages();
+        const map = new Map();
+        for (const page of pages) {
+            map.set(page.section.id, page.section);
+        }
+        return Array.from(map.values()).sort((a, b) => {
+            if (a.order !== b.order)
+                return a.order - b.order;
+            return a.label.localeCompare(b.label);
+        });
+    }
+    async function getSidebar() {
+        const [sections, pages] = await Promise.all([getSections(), getAllPages()]);
+        return sections.map((section) => ({
+            ...section,
+            pages: pages.filter((page) => page.section.id === section.id)
+        }));
+    }
+    async function getAdjacentPages(slug) {
+        const pages = await getAllPages();
+        const index = pages.findIndex((page) => page.slug === slug);
+        if (index === -1)
+            return { previous: null, next: null };
+        return {
+            previous: pages[index - 1] ?? null,
+            next: pages[index + 1] ?? null
+        };
+    }
+    async function pickLandingPage() {
+        const pages = await getAllPages();
+        return pages[0] ?? null;
+    }
+    return {
+        getAllPages,
+        getAllPagesWithContent,
+        getPageBySlug,
+        getSections,
+        getSidebar,
+        getAdjacentPages,
+        pickLandingPage
+    };
+}

package/packages/core/dist/server/index.d.ts

@@ -1,2 +1,2 @@
 export { createBlog, createRawBlog, parseMarkdownAuthorMap, parseVivaAuthorFrontmatter, parseVivaAuthorProfiles, parseVivaBlogFrontmatter, type BlogCreateConfig, type RawBlogCreateConfig, type MarkdownRenderer, type VivaAuthorFrontmatter, type VivaAuthorProfile, type VivaBlogFrontmatter, type VivaImageAsset, type VivaSeoFields } from './blog';
-export { createDocs, type DocsCreateConfig, type DocsFrontmatter, type DocsFrontmatterAdapter } from './docs';
+export { createDocs, createRawDocs, type DocsCreateConfig, type RawDocsCreateConfig, type DocsFrontmatter, type DocsFrontmatterAdapter, type DocsMarkdownRenderer } from './docs';

package/packages/core/dist/server/index.js

@@ -1,2 +1,2 @@
 export { createBlog, createRawBlog, parseMarkdownAuthorMap, parseVivaAuthorFrontmatter, parseVivaAuthorProfiles, parseVivaBlogFrontmatter } from './blog';
-export { createDocs } from './docs';
+export { createDocs, createRawDocs } from './docs';

package/packages/core/dist/types/experience.d.ts

@@ -11,3 +11,52 @@ export type ExperienceCatalog = {
     byKind: Record<ExperienceKind, ExperienceDefinition>;
     resolve: (kind?: string | null) => ExperienceDefinition;
 };
+export type SveltaNavItem = {
+    label: string;
+    href: string;
+    external?: boolean;
+};
+export type SveltaDocsPatternConfig = {
+    kind: 'docs';
+    brandName: string;
+    productName: string;
+    title: string;
+    description: string;
+    defaultSectionLabel: string;
+    sectionOrder: string[];
+    navigation: {
+        header: SveltaNavItem[];
+        footer: SveltaNavItem[];
+    };
+    search: {
+        enabled: boolean;
+        placeholder: string;
+        shortcut: string;
+    };
+    toc: {
+        enabled: boolean;
+        title: string;
+    };
+    feedback: {
+        enabled: boolean;
+        prompt: string;
+    };
+    editLinkTemplate: string;
+};
+export type SveltaBlogPatternConfig = {
+    kind: 'blog';
+    brandName: string;
+    title: string;
+    description: string;
+    pageSize: number;
+    maxPageSize: number;
+    showRss: boolean;
+    navigation: {
+        header: SveltaNavItem[];
+        footer: SveltaNavItem[];
+    };
+};
+export type SveltaPatternConfig = {
+    docs: SveltaDocsPatternConfig;
+    blog: SveltaBlogPatternConfig;
+};