### Install and Run Astro Modular Project Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/posts/getting-started.md This snippet demonstrates the basic commands to install project dependencies, run the development server, and build the project for production using pnpm. It assumes Node.js 18+ and pnpm are installed. ```bash # Install pnpm npm install -g pnpm # Install dependencies pnpm install # Preview pnpm dev # or pnpm preview # Available at http://localhost:5000 # Build for production pnpm build ``` -------------------------------- ### Homepage Layout Example: Projects Only (TypeScript) Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Illustrates a homepage setup displaying only projects. Similar to the recent posts example, this configuration results in special layout treatment with a centered 'View all projects →' link. ```typescript homeOptions: { featuredPost: { enabled: false, type: "latest", slug: undefined }, recentPosts: { enabled: false, count: 7 }, projects: { enabled: true }, docs: { enabled: false }, blurb: { placement: "none" }, } ``` -------------------------------- ### Calculus Math Examples Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates rendering of basic calculus expressions, such as derivatives and integration by parts, using KaTeX. ```markdown The derivative of $x^2$ is $\frac{d}{dx}x^2 = 2x$ Integration by parts: $$\int u \, dv = uv - \int v \, du$$ ``` -------------------------------- ### Common Mathematical Notation Examples Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Provides examples of common LaTeX commands for fractions, superscripts, subscripts, Greek letters, summation, product, integral, and limit notations. ```markdown **Fractions and Superscripts:** - Fractions: `\frac{a}{b}`, `\frac{x^2 + 1}{x - 1}` - Superscripts: `x^2`, `e^{i\pi} + 1 = 0` - Subscripts: `x_1`, `H_2O` **Greek Letters:** - Lowercase: `\alpha`, `\beta`, `\gamma`, `\delta`, `\epsilon`, `\theta`, `\lambda`, `\mu`, `\pi`, `\sigma`, `\phi`, `\omega` - Uppercase: `\Gamma`, `\Delta`, `\Theta`, `\Lambda`, `\Pi`, `\Sigma`, `\Phi`, `\Omega` **Mathematical Symbols:** - Summation: `\sum_{i=1}^{n} x_i` - Product: `\prod_{i=1}^{n} x_i` - Integral: `\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}` - Limit: `\lim_{x \to 0} \frac{\sin x}{x} = 1` ``` -------------------------------- ### Install Git on Linux Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/sourcetree-and-git-setup/index.md Commands to install the Git version control system on various Linux distributions and verify the installation. ```bash # Ubuntu/Debian sudo apt update sudo apt install git # CentOS/RHEL sudo yum install git # Verify installation git --version ``` -------------------------------- ### Bash Script for Development Setup Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/posts/formatting-reference.md A simple bash script to set up a development environment. It includes commands to install dependencies using npm and start the development server. ```bash #!/bin/bash echo "Setting up development environment..." # Install dependencies npm install # Start development server npm run dev echo "Development server started on http://localhost:3000" ``` -------------------------------- ### Asset Sync Example (File Structure) Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Illustrates how the build process automatically syncs content assets from the source directory to the public directory. This includes various media types like images, audio, video, and documents. The example shows a post's assets being copied. ```text src/content/posts/my-post/ ├── index.md ├── image.jpg ├── audio.wav ├── video.mp4 └── document.pdf ↓ (build process) ↓ public/posts/my-post/ ├── image.jpg ├── audio.wav ├── video.mp4 └── document.pdf ``` -------------------------------- ### Linear Algebra Math Example Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Shows an example of matrix multiplication rendered using LaTeX within Markdown, demonstrating the capability to display linear algebra concepts. ```markdown Matrix multiplication: $$ ``` ```markdown \begin{pmatrix} ``` ```markdown a & b \\ ``` ```markdown c & d ``` ```markdown \end{pmatrix} ``` ```markdown \begin{pmatrix} ``` ```markdown x \\ ``` ```markdown y ``` ```markdown \end{pmatrix} = ``` ```markdown ``` ```markdown \begin{pmatrix} ``` ```markdown ax + by \\ ``` ```markdown cx + dy ``` ```markdown \end{pmatrix} $$ ``` -------------------------------- ### Basic Physics Math Examples Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Provides examples of common physics formulas rendered using KaTeX, including Einstein's mass-energy equivalence and the Schrödinger equation. ```markdown Einstein's mass-energy equivalence: $E = mc^2$ The Schrödinger equation: $$ ``` ```markdown i\hbar\frac{\partial}{\partial t}\Psi(\vec{r},t) = \hat{H}\Psi(\vec{r},t) $$ ``` -------------------------------- ### Homepage Layout Example: Multiple Content Types (TypeScript) Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Presents a typical homepage configuration with multiple content types enabled, including featured post, recent posts, projects, and blurb. This setup follows the normal layout with section titles and right-aligned 'View all' links. ```typescript homeOptions: { featuredPost: { enabled: true, type: "latest", slug: undefined }, recentPosts: { enabled: true, count: 7 }, projects: { enabled: true }, docs: { enabled: false }, blurb: { placement: "below" }, } ``` -------------------------------- ### Project Command Line Execution Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Examples of standard commands used for development, building, and checking the current version of the astro-modular project. ```bash > astro-modular@0.1.0 dev C:\\Users\\david\\Development\\astro-modular > cross-env ASTRO_CONTENT_COLLECTION_CACHE=false node scripts/setup-dev.mjs && node scripts/sync-images.js && node scripts/process-aliases.js && node scripts/generate-deployment-config.js && astro dev --host localhost --port 5000 ``` ```bash > astro-modular@0.1.0 build C:\\Users\\david\\Development\\astro-modular > node scripts/sync-images.js && node scripts/process-aliases.js && node scripts/generate-deployment-config.js && astro build ``` ```bash > astro-modular@0.1.0 version C:\\Users\\david\\Development\\astro-modular > node scripts/get-version.js 0.1.0 ``` -------------------------------- ### Image Reference Formats in Markdown and Frontmatter Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Examples of how to reference images using relative paths, Obsidian bracket syntax, and YAML frontmatter configuration. ```markdown ![Image](image.jpg) ![Another Image](subfolder/image.png) ![Image]([[image.jpg]]) ![Another Image]([[subfolder/image.png]]) ``` ```yaml --- image: cover.jpg imageAlt: Cover image description --- --- image: "[[cover.jpg]]" imageAlt: Cover image description --- ``` -------------------------------- ### Piecewise Function Example Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates the LaTeX syntax for defining piecewise functions, commonly used in mathematics to define a function based on different conditions. ```markdown ```markdown $$ ``` ```markdown f(x) = \begin{cases} ``` ```markdown x^2 & \text{if } x \geq 0 \\ ``` ```markdown -x^2 & \text{if } x < 0 ``` ```markdown \end{cases} $$ ``` -------------------------------- ### Display Math Syntax Example Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Illustrates the use of double dollar signs for display math, which centers equations on a new line. This is suitable for longer or more complex mathematical expressions. ```markdown `$$...$$` (double dollar signs) Example: ```markdown $$ \int_0^{2\pi} d\theta x+e^{-i\theta} $$ ``` -------------------------------- ### Getting Astro Modular Theme Identifier Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates how to use the 'get-version.js' script to obtain the theme's version identifier. ```bash node scripts/get-version.js # Output: 0.1.0 ``` -------------------------------- ### Homepage Layout Example: Blurb Only (TypeScript) Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Shows a homepage configuration where only the blurb is enabled. This results in a page-like layout, featuring an H1 title and rounded container styling, effectively making the blurb the main content. ```typescript homeOptions: { featuredPost: { enabled: false, type: "latest", slug: undefined }, recentPosts: { enabled: false, count: 7 }, projects: { enabled: false }, docs: { enabled: false }, blurb: { placement: "below" }, } ``` -------------------------------- ### Inline Math Syntax Example Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates the use of single dollar signs for inline mathematical expressions. This syntax is commonly used for embedding short formulas within text. ```markdown `$...$` (single dollar signs) Example: `$E = mc^2$` ``` -------------------------------- ### Homepage Layout Example: Recent Posts Only (TypeScript) Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates a homepage configuration where only recent posts are enabled. This triggers a special layout treatment with a centered 'View all posts →' link instead of a section title. ```typescript homeOptions: { featuredPost: { enabled: false, type: "latest", slug: undefined }, recentPosts: { enabled: true, count: 7 }, projects: { enabled: false }, docs: { enabled: false }, blurb: { placement: "none" }, } ``` -------------------------------- ### Define Math and Mermaid Dependencies Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Required NPM dependencies for enabling math and diagram functionality in the project. ```json { "remark-math": "^6.0.0", "rehype-katex": "^7.0.0", "katex": "^0.16.9", "mermaid": "^11.1.0" } ``` -------------------------------- ### Render Mermaid Diagrams with Mermaid Syntax Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Examples of standard Mermaid diagram definitions including Gantt charts, Pie charts, and Git graphs. These diagrams are designed to be rendered within the Astro-Modular framework with theme support. ```mermaid gantt title A Gantt Diagram dateFormat YYYY-MM-DD section Section A task :a1, 2024-01-01, 30d Another task :after a1 , 20d ``` ```mermaid pie title Pets adopted by volunteers "Dogs" : 386 "Cats" : 85 "Rats" : 15 ``` ```mermaid gitGraph commit commit branch develop checkout develop commit commit checkout main merge develop ``` -------------------------------- ### Example Config Markers in TypeScript Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Illustrates the format of config markers used in src/config.ts for the Obsidian plugin. These markers, like `// [CONFIG:THEME]`, are crucial for the plugin to identify and update configuration values reliably without relying on fragile regex. ```typescript // [CONFIG:THEME] theme: "oxygen", // [CONFIG:COMMAND_PALETTE_ENABLED] enabled: true, ``` -------------------------------- ### Configure Site Settings Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/configuration.md Defines the core site metadata including site URL, title, author, and language within the src/config.ts file. ```typescript export const siteConfig = { site: 'https://yourdomain.com', title: 'Your Blog Title', description: 'Your blog description', author: 'Your Name', language: 'en', faviconThemeAdaptive: true, defaultOgImageAlt: "Astro Modular logo.", } ``` -------------------------------- ### Configure Post and Graph Options Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/configuration.md Controls global post settings such as pagination, metadata display, graph view visualization, and comment provider integration. ```typescript postOptions: { postsPerPage: 6, readingTime: true, wordCount: true, tags: true, linkedMentions: { enabled: true, linkedMentionsCompact: false, }, graphView: { enabled: true, showInSidebar: true, maxNodes: 100, showOrphanedPosts: true, }, postNavigation: true, showPostCardCoverImages: "featured-and-posts", postCardAspectRatio: "og", customPostCardAspectRatio: "2.5/1", comments: { enabled: false, provider: "giscus", }, } ``` -------------------------------- ### Customize Theme and Layout Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/configuration.md Configures global theme settings, layout dimensions, table of contents behavior, and deployment platform targets. ```typescript theme: "oxygen", customThemeFile: "custom", availableThemes: "default", fonts: { source: "local", families: { body: "Inter", heading: "Inter", mono: "JetBrains Mono", }, display: "swap", }, layout: { contentWidth: "45rem", }, tableOfContents: { enabled: true, depth: 4, }, footer: { enabled: true, content: `© 2025 {author}. Built with Astro Modular.`, showSocialIconsInFooter: true, }, hideScrollBar: false, scrollToTop: true, featureButton: "mode", deployment: { platform: "netlify", } ``` -------------------------------- ### Configure Development Settings Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Settings for handling images, content processing, error reporting, and tag management during development. ```typescript images: { showPlaceholders: true, // Show placeholder images for missing assets logMissingImages: true, // Log missing images to console fallbacks: { posts: '/posts/attachments/placeholder.jpg', pages: '/pages/attachments/placeholder.jpg', default: '/posts/attachments/placeholder.jpg' } } content: { continueOnMissingAssets: true, // Continue processing with missing assets logWarnings: true // Log content processing warnings } errors: { showDetails: true, // Show detailed error information continueOnNonCriticalErrors: true } tags: { handleMissingTags: true, // Gracefully handle missing/deleted tags logTagWarnings: true, // Log tag-related warnings continueOnMissingTags: true // Continue processing with missing tags } ``` -------------------------------- ### Configure Site Navigation Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/configuration.md Manages the main navigation menu items and social media links, including support for nested pages and icon mapping. ```typescript navigation: { showNavigation: true, style: "traditional", showMobileMenu: true, pages: [ { title: "Posts", url: "/posts/" }, { title: "Projects", url: "/projects/" }, { title: "Docs", url: "/docs/" }, { title: "About", url: "/about/", children: [...] }, ], social: [ { title: "GitHub", url: "https://github.com/username", icon: "github" }, { title: "X", url: "https://x.com/username", icon: "x-twitter" }, ], } ``` -------------------------------- ### Migrating from Environment Variables to Configuration Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates the command-line syntax for migrating from the older environment variable-based platform deployment method to the recommended configuration file approach in Astro Modular. ```bash # Old way (still works) DEPLOYMENT_PLATFORM=vercel pnpm run build # New way (recommended) # Just set platform in config.ts and run: pnpm run build ``` -------------------------------- ### Create Astro Modular Blog Project (CLI) Source: https://github.com/davidvkimball/astro-modular/blob/master/cli/README.md Command-line interface commands to scaffold a new Astro Modular blog. Supports pnpm, npm, and interactive prompts for project naming. Requires Node.js 18+ and a package manager. ```bash # pnpm pnpm create astro-modular my-blog # npm npm create astro-modular my-blog # Interactive (prompts for project name) pnpm create astro-modular ``` -------------------------------- ### Getting Current Astro Modular Theme Version Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Shows the command to execute to retrieve the current version number of the Astro Modular theme. ```bash pnpm run version # Output: 0.1.0 ``` -------------------------------- ### Integrate Re-initialization with Swup Hooks Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates how to trigger component re-initialization within the BaseLayout using Swup's page:view and visit:end hooks to ensure functionality persists across page transitions. ```javascript window.swup.hooks.on('page:view', () => { if (window.initializeMyComponent) { window.initializeMyComponent(); } }); window.swup.hooks.on('visit:end', () => { if (window.initializeMyComponent) { window.initializeMyComponent(); } }); ``` -------------------------------- ### Supported Mermaid Diagram Types Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Examples of various Mermaid diagram types supported by the theme, including flowcharts, sequence, class, state, and ER diagrams. ```mermaid graph TD A[Start] --> B{Is it?} B -->|Yes| C[OK] C --> D[Rethink] D --> B B ---->|No| E[End] ``` ```mermaid sequenceDiagram participant Alice participant Bob Alice->>Bob: Hello Bob, how are you? Bob-->>Alice: Great! ``` ```mermaid classDiagram class Animal { +String name +int age +makeSound() } class Dog { +String breed +bark() } Animal <|-- Dog ``` ```mermaid stateDiagram-v2 [*] --> Still Still --> [*] Still --> Moving Moving --> Still Moving --> Crash Crash --> [*] ``` ```mermaid erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER }|..|{ DELIVERY-ADDRESS : uses ``` -------------------------------- ### Swup Page Transition Configuration in Astro Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Illustrates the configuration of Swup for client-side page transitions within an Astro project, as defined in `astro.config.mjs`. It highlights settings for accessibility, containers, smooth scrolling, caching, preloading, and back/forward navigation handling. ```javascript export default defineConfig({ integrations: [ swup({ // options accessibility: false, containers: ['#swup-container'], smoothScrolling: false, cache: true, preload: true, skipPopStateHandling: true, }), ], }); ``` -------------------------------- ### Configure Astro Modular Site Settings Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/posts/getting-started.md This TypeScript code snippet shows how to update the essential site configuration for Astro Modular. It includes fields for the site URL, title, description, author, and language. ```typescript export const siteConfig = { site: 'https://yourdomain.com', title: 'Your Blog Title', description: 'Your blog description', author: 'Your Name', language: 'en', } ``` -------------------------------- ### Troubleshooting Math Rendering Configuration Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Provides guidance on common issues and solutions for math rendering problems, emphasizing the importance of `remarkMath` and `rehypeKatex` configuration and CSS imports. ```markdown 1. **Math not rendering**: Check that `remarkMath` and `rehypeKatex` are properly configured 2. **Styling issues**: Verify KaTeX CSS is imported in `src/styles/global.css` 3. **Theme compatibility**: Math should adapt to all themes automatically 4. **Mobile rendering**: Math should be responsive on all devices ``` -------------------------------- ### JavaScript Function Example Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/posts/formatting-reference.md A simple JavaScript function that greets a user and returns a welcome message. It demonstrates basic function definition, console logging, and variable usage. ```javascript function greetUser(name) { console.log(`Hello, ${name}!`); return `Welcome to our blog, ${name}`; } const user = "Developer"; greetUser(user); ``` -------------------------------- ### Configure Custom Theme Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Demonstrates how to configure custom themes by setting the `theme` to 'custom' and specifying the `customThemeFile` in `src/config.ts`. This allows for user-defined themes. ```typescript theme: "custom" customThemeFile: "filename" ``` -------------------------------- ### Version Management Functions in get-version.js Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Lists the available functions within the 'scripts/get-version.js' utility for managing the Astro Modular theme's version information, including getting the version, name, identifier, and updating the version. ```javascript // getThemeVersion() - Get current version from VERSION file or package.json // getThemeName() - Get theme name from package.json // getThemeIdentifier() - Get full identifier (name@version) // updateVersion(newVersion) - Update both VERSION file and package.json ``` -------------------------------- ### Configure KaTeX Theme Integration Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md CSS styles to ensure KaTeX math rendering respects the project's theme colors and spacing requirements. ```css .katex { font-size: 1.1em; color: rgb(var(--color-foreground)); } .katex-display { margin: 1.5rem 0; text-align: center; } .dark .katex { color: rgb(var(--color-foreground)); } ``` -------------------------------- ### Using `entry.id` instead of `entry.slug` in Astro v6+ Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md This TypeScript example shows the correct way to generate URLs for collection entries in Astro v6 and later. It replaces the deprecated `entry.slug` with the modern `entry.id`, which now serves as the slug. Using `entry.slug` will result in 'undefined' URLs. ```typescript // ❌ WRONG - slug is deprecated url: `/posts/${post.slug}`, // ✅ CORRECT - id is the modern API url: `/posts/${post.id}` ``` -------------------------------- ### HTML Buttons with Theming Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/posts/formatting-reference.md Demonstrates how to create styled buttons using HTML and CSS classes. These buttons adapt to light/dark themes and can be wrapped in links for navigation. No external JavaScript dependencies are required. ```html
``` ```html
``` -------------------------------- ### Configure Git Identity Source: https://github.com/davidvkimball/astro-modular/blob/master/src/content/docs/sourcetree-and-git-setup/index.md Sets the global user name and email address associated with Git commits. ```bash git config --global user.name "Your Name" git config --global user.email "your.email@example.com" ``` -------------------------------- ### Project CLI Scripts Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md A list of essential scripts for development, production builds, and content management tasks within the Astro Modular project. ```bash pnpm run dev # Start development server pnpm run build # Build for production pnpm run check-images # Check for missing images pnpm run sync-images # Sync images from content to public pnpm run process-aliases # Process content aliases pnpm run generate-deployment-config # Generate deployment configs ``` -------------------------------- ### Configure Profile Picture Source: https://github.com/davidvkimball/astro-modular/blob/master/AGENTS.md Manages the display, placement, and styling of the user profile picture in the header or footer. ```typescript profilePicture: { enabled: true, image: "/profile.jpg", // Path to your image (place in public/ directory) alt: "Profile picture", // Alt text for accessibility size: "md", // "sm" (32px), "md" (48px), or "lg" (64px) url: "/about", // Optional URL to link to when clicked placement: "footer", // "footer" or "header" style: "circle", // "circle", "square", or "none" } ``` -------------------------------- ### GET /api/posts.json Source: https://context7.com/davidvkimball/astro-modular/llms.txt Endpoint for fetching posts data, typically used for command palette search functionality. Returns an array of posts. ```APIDOC ## GET /api/posts.json ### Description Endpoint for fetching posts data, typically used for command palette search functionality. Returns an array of posts. ### Method GET ### Endpoint /api/posts.json ### Parameters None ### Request Body None ### Response #### Success Response (200) - **id** (string) - Unique identifier for the post. - **title** (string) - The title of the post. - **description** (string) - A brief description of the post. - **url** (string) - The URL to the post. - **type** (string) - The type of content, always "post". - **date** (string) - The publication date of the post. - **tags** (string[]) - An array of tags associated with the post. #### Response Example ```json [ { "id": "post-1", "title": "First Post", "description": "This is the first post.", "url": "/posts/first-post", "type": "post", "date": "2023-01-01T00:00:00.000Z", "tags": ["intro", "getting-started"] } ] ``` **Note**: Response includes caching headers: `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` ```