@classic-homes/theme-docs 0.0.2

package/dist/lib/styles/markdown.css

@@ -0,0 +1,516 @@
+/**
+ * Markdown Content Styles
+ *
+ * Provides comprehensive styling for rendered markdown content.
+ * Uses Tailwind CSS utility classes and design token CSS variables.
+ *
+ * Usage:
+ *   import '@classic-homes/theme-docs/styles';
+ *
+ * Required CSS Variables:
+ * These HSL color channel values must be defined in your CSS (typically via @classic-homes/theme-tokens):
+ *
+ *   --foreground         - Main text color (e.g., "222 84% 5%" for dark text)
+ *   --muted-foreground   - Secondary/muted text color
+ *   --primary            - Primary accent color for links and highlights
+ *   --muted              - Muted background color for code blocks, tables
+ *   --border             - Border color for dividers, code blocks, tables
+ *
+ * Example CSS variable definitions:
+ *   :root {
+ *     --foreground: 222.2 84% 4.9%;
+ *     --muted-foreground: 215.4 16.3% 46.9%;
+ *     --primary: 222.2 47.4% 11.2%;
+ *     --muted: 210 40% 96.1%;
+ *     --border: 214.3 31.8% 91.4%;
+ *   }
+ */
+
+.markdown-content {
+  color: hsl(var(--foreground));
+  line-height: 1.7;
+}
+
+/* Headings */
+.markdown-content h1 {
+  font-size: 1.875rem;
+  line-height: 2.25rem;
+  font-weight: 700;
+  color: hsl(var(--foreground));
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  padding-bottom: 0.75rem;
+  border-bottom: 1px solid hsl(var(--border));
+}
+
+.markdown-content h2 {
+  font-size: 1.5rem;
+  line-height: 2rem;
+  font-weight: 700;
+  color: hsl(var(--foreground));
+  margin-top: 2rem;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid hsl(var(--border));
+}
+
+.markdown-content h3 {
+  font-size: 1.25rem;
+  line-height: 1.75rem;
+  font-weight: 600;
+  color: hsl(var(--foreground));
+  margin-top: 1.5rem;
+  margin-bottom: 0.75rem;
+}
+
+.markdown-content h4 {
+  font-size: 1.125rem;
+  line-height: 1.75rem;
+  font-weight: 600;
+  color: hsl(var(--foreground));
+  margin-top: 1rem;
+  margin-bottom: 0.5rem;
+}
+
+.markdown-content h5 {
+  font-size: 1rem;
+  line-height: 1.5rem;
+  font-weight: 600;
+  color: hsl(var(--foreground));
+  margin-top: 0.75rem;
+  margin-bottom: 0.5rem;
+}
+
+.markdown-content h6 {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 600;
+  /* Use foreground with slight opacity for better contrast than muted-foreground */
+  color: hsl(var(--foreground) / 0.85);
+  margin-top: 0.75rem;
+  margin-bottom: 0.5rem;
+}
+
+/* First heading should not have top margin */
+.markdown-content > h1:first-child,
+.markdown-content > h2:first-child,
+.markdown-content > h3:first-child {
+  margin-top: 0;
+}
+
+/* Paragraphs */
+.markdown-content p {
+  margin-bottom: 1rem;
+  color: hsl(var(--muted-foreground));
+}
+
+/* Links */
+.markdown-content a {
+  color: hsl(var(--primary));
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  transition: color 0.2s;
+}
+
+.markdown-content a:hover {
+  color: hsl(var(--primary) / 0.8);
+}
+
+/* Lists */
+.markdown-content ul {
+  list-style-type: disc;
+  list-style-position: inside;
+  margin-bottom: 1rem;
+  color: hsl(var(--muted-foreground));
+}
+
+.markdown-content ol {
+  list-style-type: decimal;
+  list-style-position: inside;
+  margin-bottom: 1rem;
+  color: hsl(var(--muted-foreground));
+}
+
+.markdown-content li {
+  margin-left: 1rem;
+  margin-bottom: 0.5rem;
+}
+
+.markdown-content ul ul,
+.markdown-content ol ul,
+.markdown-content ul ol,
+.markdown-content ol ol {
+  margin-left: 1.5rem;
+  margin-top: 0.5rem;
+  margin-bottom: 0;
+}
+
+/* Code blocks - Shiki handles syntax colors, we handle layout */
+.markdown-content pre {
+  border-radius: 0.5rem;
+  padding: 1rem;
+  margin-bottom: 1rem;
+  overflow-x: auto;
+  border: 1px solid hsl(var(--border));
+}
+
+.markdown-content pre code {
+  background: transparent;
+  padding: 0;
+  font-size: 0.875rem;
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+}
+
+/* Inline code */
+.markdown-content code {
+  background: hsl(var(--muted));
+  color: hsl(var(--foreground));
+  padding: 0.125rem 0.375rem;
+  border-radius: 0.25rem;
+  font-size: 0.875rem;
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+}
+
+/* Blockquotes */
+.markdown-content blockquote {
+  border-left: 4px solid hsl(var(--primary));
+  background: hsl(var(--muted) / 0.5);
+  padding: 0.75rem 1rem;
+  margin-bottom: 1rem;
+  font-style: italic;
+  color: hsl(var(--muted-foreground));
+}
+
+.markdown-content blockquote p {
+  margin-bottom: 0;
+}
+
+/* Horizontal rules */
+.markdown-content hr {
+  margin: 2rem 0;
+  border: none;
+  border-top: 1px solid hsl(var(--border));
+}
+
+/* Tables */
+.markdown-content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1rem;
+  font-size: 0.875rem;
+}
+
+.markdown-content thead {
+  background: hsl(var(--muted));
+}
+
+.markdown-content th {
+  border: 1px solid hsl(var(--border));
+  padding: 0.5rem 1rem;
+  text-align: left;
+  font-weight: 600;
+  color: hsl(var(--foreground));
+}
+
+.markdown-content td {
+  border: 1px solid hsl(var(--border));
+  padding: 0.5rem 1rem;
+  color: hsl(var(--muted-foreground));
+}
+
+.markdown-content tbody tr:nth-child(even) {
+  background: hsl(var(--muted) / 0.5);
+}
+
+/* Strong/Bold */
+.markdown-content strong {
+  font-weight: 600;
+  color: hsl(var(--foreground));
+}
+
+/* Emphasis/Italic */
+.markdown-content em {
+  font-style: italic;
+}
+
+/* Images */
+.markdown-content img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.5rem;
+  border: 1px solid hsl(var(--border));
+  margin: 1rem 0;
+}
+
+/* Task lists */
+.markdown-content input[type='checkbox'] {
+  margin-right: 0.5rem;
+}
+
+/* Shiki code block styling overrides */
+.markdown-content .shiki {
+  border-radius: 0.5rem;
+  padding: 1rem;
+  margin-bottom: 1rem;
+  overflow-x: auto;
+  border: 1px solid hsl(var(--border));
+}
+
+/* Code block wrapper styling */
+.code-block-wrapper {
+  margin-bottom: 1rem;
+}
+
+.code-block-wrapper .shiki {
+  margin-bottom: 0;
+}
+
+.code-block-wrapper:has(.code-block-filename) .shiki {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+/* ==========================================================================
+   Admonitions / Callouts
+   ========================================================================== */
+
+.markdown-content .admonition {
+  margin: 1.5rem 0;
+  border-radius: 0.5rem;
+  border: 1px solid hsl(var(--border));
+  overflow: hidden;
+}
+
+.markdown-content .admonition-heading {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1rem;
+  font-weight: 600;
+  font-size: 0.875rem;
+}
+
+.markdown-content .admonition-icon {
+  width: 1.25rem;
+  height: 1.25rem;
+  flex-shrink: 0;
+}
+
+.markdown-content .admonition-content {
+  padding: 0 1rem 1rem;
+}
+
+.markdown-content .admonition-content > :first-child {
+  margin-top: 0;
+}
+
+.markdown-content .admonition-content > :last-child {
+  margin-bottom: 0;
+}
+
+/* Note - Blue */
+.markdown-content .admonition-note {
+  border-color: hsl(210 100% 50% / 0.3);
+  background: hsl(210 100% 50% / 0.05);
+}
+
+.markdown-content .admonition-note .admonition-heading {
+  background: hsl(210 100% 50% / 0.1);
+  color: hsl(210 100% 40%);
+}
+
+/* Tip - Green */
+.markdown-content .admonition-tip {
+  border-color: hsl(142 71% 45% / 0.3);
+  background: hsl(142 71% 45% / 0.05);
+}
+
+.markdown-content .admonition-tip .admonition-heading {
+  background: hsl(142 71% 45% / 0.1);
+  color: hsl(142 71% 35%);
+}
+
+/* Warning - Yellow/Orange */
+.markdown-content .admonition-warning {
+  border-color: hsl(38 92% 50% / 0.3);
+  background: hsl(38 92% 50% / 0.05);
+}
+
+.markdown-content .admonition-warning .admonition-heading {
+  background: hsl(38 92% 50% / 0.1);
+  color: hsl(38 92% 35%);
+}
+
+/* Important - Purple */
+.markdown-content .admonition-important {
+  border-color: hsl(265 83% 57% / 0.3);
+  background: hsl(265 83% 57% / 0.05);
+}
+
+.markdown-content .admonition-important .admonition-heading {
+  background: hsl(265 83% 57% / 0.1);
+  color: hsl(265 83% 45%);
+}
+
+/* Caution - Red */
+.markdown-content .admonition-caution {
+  border-color: hsl(0 84% 60% / 0.3);
+  background: hsl(0 84% 60% / 0.05);
+}
+
+.markdown-content .admonition-caution .admonition-heading {
+  background: hsl(0 84% 60% / 0.1);
+  color: hsl(0 84% 45%);
+}
+
+/* ==========================================================================
+   Footnotes
+   ========================================================================== */
+
+.markdown-content .footnotes {
+  margin-top: 3rem;
+  font-size: 0.875rem;
+}
+
+.markdown-content .footnotes-separator {
+  margin-bottom: 1.5rem;
+}
+
+.markdown-content .footnotes-list {
+  padding-left: 1.5rem;
+  color: hsl(var(--muted-foreground));
+}
+
+.markdown-content .footnote-item {
+  margin-bottom: 0.5rem;
+}
+
+.markdown-content .footnote-item p {
+  display: inline;
+  margin: 0;
+}
+
+.markdown-content .footnote-backref {
+  margin-left: 0.25rem;
+  text-decoration: none;
+  font-size: 0.75rem;
+}
+
+.markdown-content .footnote-ref a {
+  text-decoration: none;
+  color: hsl(var(--primary));
+  font-size: 0.75rem;
+}
+
+.markdown-content .footnote-ref a:hover {
+  text-decoration: underline;
+}
+
+/* ==========================================================================
+   Definition Lists
+   ========================================================================== */
+
+.markdown-content .definition-list {
+  margin-bottom: 1.5rem;
+}
+
+.markdown-content .definition-list dt {
+  font-weight: 600;
+  color: hsl(var(--foreground));
+  margin-top: 1rem;
+}
+
+.markdown-content .definition-list dt:first-child {
+  margin-top: 0;
+}
+
+.markdown-content .definition-list dd {
+  margin-left: 1.5rem;
+  margin-top: 0.25rem;
+  color: hsl(var(--muted-foreground));
+}
+
+/* ==========================================================================
+   Mermaid Diagrams
+   ========================================================================== */
+
+.markdown-content .mermaid-diagram {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  background: hsl(var(--muted) / 0.3);
+  border: 1px solid hsl(var(--border));
+  border-radius: 0.5rem;
+  overflow-x: auto;
+}
+
+.markdown-content .mermaid-diagram.mermaid-rendered {
+  display: flex;
+  justify-content: center;
+}
+
+.markdown-content .mermaid-diagram svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.markdown-content .mermaid-diagram pre.mermaid {
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  border: none;
+  font-size: 0.875rem;
+  color: hsl(var(--muted-foreground));
+}
+
+/* Standalone Mermaid component styles */
+.mermaid-container {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  background: hsl(var(--muted) / 0.3);
+  border: 1px solid hsl(var(--border));
+  border-radius: 0.5rem;
+  overflow-x: auto;
+}
+
+.mermaid-container svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.mermaid-fallback {
+  margin: 0;
+  padding: 0.5rem;
+  background: transparent;
+  border: none;
+  font-size: 0.875rem;
+  color: hsl(var(--muted-foreground));
+}
+
+.mermaid-error {
+  border-color: hsl(0 84% 60% / 0.3);
+  background: hsl(0 84% 60% / 0.05);
+}
+
+.mermaid-error-message {
+  color: hsl(0 84% 45%);
+}
+
+.mermaid-error-title {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+
+.mermaid-error-code {
+  margin: 0.5rem 0;
+  padding: 0.5rem;
+  background: hsl(var(--muted) / 0.5);
+  border-radius: 0.25rem;
+  font-size: 0.75rem;
+}
+
+.mermaid-error-details {
+  font-size: 0.75rem;
+  margin: 0;
+}

package/dist/lib/types/docs.d.ts

@@ -0,0 +1,72 @@
+/**
+ * DocsHub Configuration Types
+ */
+/** Individual documentation item */
+export interface DocsItem {
+    /** Display title */
+    title: string;
+    /** Brief description */
+    description?: string;
+    /** Link/route to the document */
+    href: string;
+    /** Icon identifier or component */
+    icon?: string;
+    /** Tags for filtering */
+    tags?: string[];
+    /** Whether item is new/updated */
+    badge?: 'new' | 'updated' | 'deprecated' | string;
+    /** External link (opens in new tab) */
+    external?: boolean;
+}
+/** Documentation section/category */
+export interface DocsSection {
+    /** Section identifier */
+    id: string;
+    /** Section title */
+    title?: string;
+    /** Section description */
+    description?: string;
+    /** Items in this section */
+    items: DocsItem[];
+    /** Collapse section by default */
+    collapsed?: boolean;
+}
+/** Full DocsHub configuration */
+export interface DocsHubConfig {
+    /** Documentation sections */
+    sections: DocsSection[];
+    /** Optional search configuration */
+    search?: {
+        enabled: boolean;
+        placeholder?: string;
+    };
+}
+/** DocsHub component props */
+export interface DocsHubProps {
+    config: DocsHubConfig;
+    columns?: 1 | 2 | 3 | 4;
+    class?: string;
+}
+/** DocsCard component props */
+export interface DocsCardProps {
+    item: DocsItem;
+    class?: string;
+}
+/** TableOfContents heading entry */
+export interface TocEntry {
+    /** Heading text */
+    text: string;
+    /** Heading level (1-6) */
+    level: number;
+    /** Generated ID for linking */
+    id: string;
+}
+/** TableOfContents component props */
+export interface TableOfContentsProps {
+    /** HTML content to extract headings from */
+    html: string;
+    /** Maximum heading depth to include (default: 3) */
+    maxDepth?: number;
+    /** Custom class */
+    class?: string;
+}

package/dist/lib/types/docs.js

@@ -0,0 +1,4 @@
+/**
+ * DocsHub Configuration Types
+ */
+export {};

package/dist/lib/types/frontmatter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Frontmatter Types for Documentation
+ */
+/** Author information as an object */
+export interface AuthorInfo {
+    /** Author's display name */
+    name: string;
+    /** Author's email address */
+    email?: string;
+    /** URL to author's avatar image */
+    avatar?: string;
+}
+/** Standard frontmatter fields */
+export interface FrontmatterData {
+    /** Document title */
+    title?: string;
+    /** Document description/summary */
+    description?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Publication/last updated date (ISO 8601 string or Date object) */
+    date?: string | Date;
+    /** Author - can be a simple name string or detailed author info */
+    author?: string | AuthorInfo;
+    /** Document category */
+    category?: string;
+    /** Sort order within category (lower numbers appear first) */
+    order?: number;
+    /** Whether document is draft (not for production) */
+    draft?: boolean;
+    /** Custom icon (emoji or icon name for DocsHub cards) */
+    icon?: string;
+    /** Estimated reading time (e.g., "5 min read") */
+    readingTime?: string;
+    /** Related document slugs for cross-linking */
+    related?: string[];
+    /**
+     * Custom metadata fields - allows extending frontmatter with additional properties.
+     * Note: Type safety is not enforced for custom fields. Consider creating a
+     * specific interface extending FrontmatterData for your project's needs.
+     */
+    [key: string]: unknown;
+}
+/** Parsed markdown result */
+export interface ParsedMarkdown {
+    /** Extracted frontmatter data */
+    frontmatter: FrontmatterData | null;
+    /** Raw markdown content (without frontmatter) */
+    markdown: string;
+    /** Rendered HTML content */
+    html: string;
+}
+/** Parser options */
+export interface ParseOptions {
+    /** Shiki theme for code highlighting */
+    theme?: string;
+    /** Whether to generate heading IDs */
+    generateHeadingIds?: boolean;
+}
+/** MarkdownPage component props */
+export interface MarkdownPageProps {
+    /** Raw markdown content (with optional frontmatter) */
+    content: string;
+    /** Custom class for the content container */
+    class?: string;
+    /** Shiki theme to use */
+    theme?: 'github-dark' | 'github-light' | 'one-dark-pro' | string;
+}

package/dist/lib/types/frontmatter.js

@@ -0,0 +1,4 @@
+/**
+ * Frontmatter Types for Documentation
+ */
+export {};

package/dist/lib/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type exports for @classic-homes/theme-docs
+ */
+export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, MarkdownPageProps, } from './frontmatter.js';
+export type { DocsItem, DocsSection, DocsHubConfig, DocsHubProps, DocsCardProps, TocEntry, TableOfContentsProps, } from './docs.js';

package/dist/lib/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type exports for @classic-homes/theme-docs
+ */
+export {};

package/dist/lib/utils.d.ts

@@ -0,0 +1,6 @@
+import { type ClassValue } from 'clsx';
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Uses clsx for conditional classes and tailwind-merge to handle conflicts
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/utils.js

@@ -0,0 +1,9 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Uses clsx for conditional classes and tailwind-merge to handle conflicts
+ */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}