### Configure ContentApp with Layouts

Source: https://docs.jaspr.site/content/quick_start

Shows how to configure ContentApp to use provided or custom layouts. DocsLayout is presented as an example, offering a structured documentation interface with header, sidebar, and table of contents.

```dart
ContentApp(
  layouts: [
    DocsLayout()
  ],
)
```

--------------------------------

### Create Jaspr Project with Documentation Template

Source: https://docs.jaspr.site/content/quick_start

This command creates a new Jaspr project pre-configured with the Documentation Template, providing a functional documentation site out-of-the-box. No manual setup is required.

```bash
jaspr create --template=docs my_documentation_site
```

--------------------------------

### Configure ContentApp with Frontmatter

Source: https://docs.jaspr.site/content/quick_start

Demonstrates how to use Frontmatter in Markdown files to add metadata such as title and description. This metadata can then be used by the ContentApp.

```markdown
---
title: My Page Title
description: My Page Description
---

...
```

--------------------------------

### Sample Markdown Content (content/index.md)

Source: https://docs.jaspr.site/content/quick_start

An example of a Markdown file that can be used within the content directory. It demonstrates standard Markdown syntax, including lists, blockquotes, code blocks, links, images, and tables.

```markdown
# Welcome to Jaspr Content

This is a sample content file. You can add more files here as needed.

---

All standard **markdown syntax** is supported, including:

**Lists**:

- Item 1
- Item 2
  1. Nested item
  2. Nested item 2

**Blockquotes**:

> This is a blockquote.  
> It can span multiple lines.

**Code blocks**:

```dart
void main() {
  print('Hello, world!');
}
```

**Inline code**: Use `print('Hello, world!')` to display a message.

**Links**: [Visit Jaspr](https://jaspr.dev)

**Images**: ![Sample Image](https://placehold.co/600x400)

**Tables**:

| Syntax    | Description |
|-----------|-------------|
| Header 1  | Content 1   |
| Header 2  | Content 2   |

```

--------------------------------

### Initialize Jaspr and ContentApp (main.server.dart)

Source: https://docs.jaspr.site/content/quick_start

This Dart code initializes the Jaspr application and configures it to use jaspr_content. It sets up the default server options and registers MarkdownParser to handle content files.

```dart
import 'package:jaspr/jaspr.dart';
import 'package:jaspr_content/jaspr_content.dart';

import 'main.server.options.dart';

void main() {
  Jaspr.initializeApp(options: defaultServerOptions);

  runApp(ContentApp(
    parsers: [
      MarkdownParser(),
    ],
  ));
}

```

--------------------------------

### Configure ContentApp with Template Engine

Source: https://docs.jaspr.site/content/quick_start

Demonstrates the integration of a template engine, specifically MustacheTemplateEngine, to enable templating syntax within Markdown files. This allows for dynamic content generation using variables and conditionals.

```dart
ContentApp(
  templateEngine: MustacheTemplateEngine(),
)
```

--------------------------------

### Configure BlogLayout Header with Links and Toggles

Source: https://docs.jaspr.site/content/concepts/page_layouts

Example of how to use the `Header` component within a `BlogLayout`. It includes setting the site title, logo, navigation links, and interactive components like `ThemeToggle` and `GitHubButton`.

```dart
BlogLayout(
  header: Header(
    title: 'My Site',
    logo: '/assets/logo.png',
    items: [
      Link(text: 'Home', href: '/'),
      Link(text: 'Articles', href: '/articles'),
      ThemeToggle(), // Described below
      GitHubButton(repo: '<user>/<repo>'), // Described below
    ],
  )
)
```

--------------------------------

### Configure DocsLayout Sidebar with Groups and Links

Source: https://docs.jaspr.site/content/concepts/page_layouts

This snippet illustrates the setup of a `Sidebar` component for a `DocsLayout`. It demonstrates organizing navigation links into collapsible groups using `SidebarGroup` and `SidebarLink`.

```dart
DocsLayout(
  sidebar: Sidebar(groups: [
    SidebarGroup(
      links: [
        SidebarLink(text: "📖 Overview", href: '/'),
        SidebarLink(text: "🧭 About", href: '/about'),
      ],
    ),
    SidebarGroup(title: 'Get Started', links: [
      SidebarLink(text: "🚀 Quick Start", href: '/get_started/quick_start'),
    ]),
  ]),
)
```

--------------------------------

### Install and Deploy with Globe CLI

Source: https://docs.jaspr.site/concepts/deploying

Instructions for installing the Globe CLI and deploying a Jaspr project. The Globe CLI simplifies the deployment process by automatically detecting project configurations. It guides the user through project linking on the first deployment.

```bash
dart pub global activate globe_cli

```

```bash
globe deploy --prod

```

--------------------------------

### Configure ContentApp with Custom Components

Source: https://docs.jaspr.site/content/quick_start

Illustrates how to integrate custom components like Callout and CodeBlock into ContentApp. These components can enhance content presentation with features like info boxes and syntax-highlighted code blocks.

```dart
ContentApp(
  components: [
    Callout(), // Callout boxes, like <Info>, <Warning>, <Success> and <Error>
    CodeBlock(), // Code block with syntax highlighting and copy button
  ],
)
```

--------------------------------

### Using Mustache Templating in Markdown

Source: https://docs.jaspr.site/content/quick_start

Shows an example of using the Mustache templating engine within a Markdown file. It utilizes Frontmatter data and conditional rendering to display dynamic content, such as a banner based on a page variable.

```markdown
---
title: My Page Title
showBanner: true
---

This markdown content is pre-processed using the **Mustache** templating engine. This allows you to use variables and conditionals in your content:

{{#page.showBanner}}
<Info>
  This is a banner for {{page.title}}.
</Info>
{{/page.showBanner}}
```

--------------------------------

### Configure FilesystemLoader with ContentApp

Source: https://docs.jaspr.site/content/concepts/route_loading

This example shows how to configure Jaspr's ContentApp to use the FilesystemLoader, which loads pages from a local directory. The default ContentApp constructor includes a FilesystemLoader, or it can be explicitly provided in a custom setup.

```dart
ContentApp(
  directory: 'content' // Loads pages from the 'content' directory (default).
  // ...
);

// OR

ContentApp.custom(
  loaders: [
    FilesystemLoader('content'), // Loads pages from the 'content' directory.
  ],
  // ...
);
```

--------------------------------

### Private Files and Partial Inclusion

Source: https://docs.jaspr.site/content/guides/adding_pages

Illustrates how files and folders starting with '_' or '.' are ignored, and how to include partial files using templating syntax (e.g., mustache).

```plaintext
content/
 ├── index.md
 └── _partials/
    ├── header.md
    └── footer.md
```

```mustache
{{> _partials/header }}

# My Page Title
This is the normal content of the page.

{{> _partials/footer }}
```

--------------------------------

### Loading Content from GitHub

Source: https://docs.jaspr.site/content/guides/adding_pages

Demonstrates how to use the GitHubLoader to fetch content from a GitHub repository, specifying the repository path, a sub-directory, and an optional access token.

```dart
ContentApp.custom(
  loaders: [
    GitHubLoader(
      '<username>/<repo>'
      path: 'docs/',
      accessToken: '...'
    ),
  ],
  ...
);
```

--------------------------------

### Initialize ContentApp with Theme (Dart)

Source: https://docs.jaspr.site/content/concepts/theming

Demonstrates how to initialize the ContentApp with a custom theme. The 'theme' parameter accepts an instance of ContentTheme for customization.

```dart
import 'package:jaspr_content/theme.dart';

ContentApp(
  // ... other configurations
  theme: ContentTheme(
    // Theme customizations go here
  ),
)
```

--------------------------------

### Jaspr Router Setup

Source: https://docs.jaspr.site/concepts/routing

This snippet demonstrates the basic setup for routing in a Jaspr application. It involves importing the `jaspr_router` package and defining routes using the `Router` and `Route` components. The `Router` component takes a list of `Route` objects, each specifying a path and a builder function to render the corresponding component. This setup is foundational for navigating between different pages in a Jaspr web application.

```dart
import 'package:jaspr_router/jaspr_router.dart';

import 'pages/home.dart';
import 'pages/about.dart' ;

class App extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return Router(routes: [
      Route(path: '/', builder: (context, state) => Home()),
      Route(path: '/about', builder: (context, state) => About()),
    ]);
  }
}

```

--------------------------------

### Jaspr Project Structure Example

Source: https://docs.jaspr.site/get_started/configuration

Recommended project structure for a Jaspr website, illustrating directories for components, pages, entrypoints, and static assets. Varies based on rendering mode.

```bash
├── lib/
│   ├── components/      // Shared components
│   │   ├── counter.dart
│   │   └── ...
│   ├── pages/           // The pages of your website
│   │   ├── home.dart
│   │   └── ...
│   ├── app.dart         // The main app component, usually containing the Router
│   ├── ...
│   ├── main.client.dart // The client entrypoint, for all modes, optional
│   ├── main.client.options.dart // Auto-generated by Jaspr
│   ├── main.server.dart // The server entrypoint, only for server or static mode
│   └── main.server.optionsdart // Auto-generated by Jaspr
├── web/.                // Static assets
│   ├── images/
│   │   └── ...
│   ├── styles.css       // Usually only for client mode
│   └── index.html       // The index file, only for client mode
├── pubspec.lock
└── pubspec.yaml

```

--------------------------------

### Using YAML Data in Markdown with Mustache

Source: https://docs.jaspr.site/content/quick_start

Provides an example of accessing data loaded from a YAML file (e.g., 'faq.yaml') within a Markdown file using Mustache templating. This allows for dynamic rendering of content, such as displaying a list of frequently asked questions.

```markdown
---
title: FAQ
---

# Frequently Asked Questions

{{#faq}}
## {{question}}
> {{answer}}
{{/faq}}
```

--------------------------------

### Using Jaspr Components in Content

Source: https://docs.jaspr.site/content/quick_start

Explains how to use Jaspr components directly within content files using HTML-like syntax. It showcases the Callout component for styled messages and the CodeBlock component for syntax highlighting and a copy button.

```html
<Info>
  This is an info box.
</Info>

```dart
void main() {
  print('Hello, world!');
}
```
```

--------------------------------

### Info Callout Example

Source: https://docs.jaspr.site/content/components/callout

An example of using the `<Info>` callout variant to display a soft blue box with an info icon. This is suitable for drawing attention to useful page information.

```html
<Info>This draws attention to useful page information.</Info>

```

--------------------------------

### Jaspr CLI: Serve Project

Source: https://docs.jaspr.site/get_started/cli

Starts a development server for a Jaspr project. This server watches project files for changes and automatically rebuilds the project, providing a live-reloading development experience.

```bash
jaspr serve

```

--------------------------------

### Example Sitemap XML Output

Source: https://docs.jaspr.site/concepts/static_sites

Provides an example of the XML structure for a sitemap generated by Jaspr. This snippet showcases how the `changefreq` and `priority` settings, when applied to a route, are reflected in the `sitemap.xml` file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  ...
  <url>
    <loc>https://example.com/summary</loc>
    <changefreq>weekly</changefreq>
    <priority>0.9</priority>
  </url>
  ...
</urlset>

```

--------------------------------

### Configuring Multiple Page Parsers

Source: https://docs.jaspr.site/content/guides/adding_pages

Shows how to configure the ContentApp to use multiple PageParsers, such as MarkdownParser and HtmlParser, allowing for mixed file formats in the content directory.

```dart
ContentApp(
  parsers: [
    MarkdownParser(),
    HtmlParser(),
  ],
);
```

--------------------------------

### Create a Custom Page Layout (Dart)

Source: https://docs.jaspr.site/content/concepts/page_layouts

Provides an example of creating a custom page layout by extending Jaspr's `PageLayoutBase`. This includes defining a unique name, customizing the head section with styles, and building the body structure.

```dart
import 'package:jaspr/jaspr.dart';
import 'package:jaspr_content/jaspr_content.dart';

class MyCustomLayout extends PageLayoutBase {
  const MyCustomLayout();

  @override
  Pattern get name => 'my_custom_layout_name'; // To be used in frontmatter.

  @override
  Iterable<Component> buildHead(Page page) sync* {
    // Add common meta tags.
    yield* super.buildHead(page);

    yield Style(styles: [
      css('.custom_layout', [
        // Add custom css rules for this layout.
      ]),
    ]);
  }

  @override
  Component buildBody(Page page, Component child) {
    // `page` contains all page data, including frontmatter.
    // `child` is the rendered content of the page.
    
    return div(classes: 'custom_layout', [
      header([
        // Add a custom header.
      ]),
      main_([
        child,
      ]),
      footer([
        // Add a custom footer.
      ]),
    ]);
  }
}

```

--------------------------------

### Markdown Syntax Example

Source: https://docs.jaspr.site/content/guides/writing_content

Demonstrates standard Markdown syntax for headings, lists, links, and images. Jaspr supports common Markdown features out-of-the-box.

```markdown
# Heading 1
## Heading 2

- List item 1
- List item 2

[Link text](https://example.com)

```

--------------------------------

### Data File Example (YAML)

Source: https://docs.jaspr.site/content/guides/writing_content

Provides an example of a YAML data file located in the `/content/_data` directory. This data can be accessed within markdown files using its corresponding variable name.

```yaml
- question: What is Jaspr?
  answer: Jaspr is a framework for building web applications in Dart.
- question: How do I get started?
  answer: You can get started by following the [quick start guide](/quick_start).

```

--------------------------------

### StatelessComponent Example in Dart

Source: https://docs.jaspr.site/concepts/components

Demonstrates the structure of a custom StatelessComponent in Jaspr, similar to Flutter's StatelessWidget. It extends StatelessComponent and provides a build method to define its UI.

```dart
class MyComponent extends StatelessComponent {
  const MyComponent({Key? key}): super(key: key);

  @override
  Component build(BuildContext context) {
    return p([ .text('Hello World') ]);
  }
}
```

--------------------------------

### Mustache Templating Example

Source: https://docs.jaspr.site/content/guides/writing_content

Shows how to use Mustache templating in Jaspr content to dynamically render variables defined in the frontmatter. All frontmatter data is accessible under the `page` key.

```mustache
---
name: Kilian
---

Hello {{page.name}}!

```

--------------------------------

### Frontmatter Example

Source: https://docs.jaspr.site/content/guides/writing_content

Illustrates the YAML frontmatter block at the beginning of a content file, used for defining page metadata like title, description, and custom fields.

```yaml
---
title: My Page Title
description: A short description of the page.
custom_field: Custom value
---

*Normal content*

```

--------------------------------

### Select Input with Options in Jaspr

Source: https://docs.jaspr.site/concepts/html

Illustrates creating a dropdown select element with options using Jaspr components. This example demonstrates setting `value` and `selected` attributes for the option elements.

```dart
select([\n  option(value: 'test', [.text('Select me!')]),\n  option(value: 'other', selected: true, [.text('Or me!')])\n])
```

--------------------------------

### Basic Document Setup with Document() Constructor (Server-side Dart)

Source: https://docs.jaspr.site/api/components/document

Demonstrates the use of the `Document()` constructor in Dart for setting up the basic HTML structure of a website on the server. It allows configuration of title, meta tags, and the main body content. This is only available on the server using `package:jaspr/server.dart`.

```dart
void main() {
  runApp(Document(
    title: "My Site",
    meta: {
      "description": "My site description",
    },
    body: div(id: "main", []),
  ));
}
```

--------------------------------

### Client Entrypoint: Basic Manual Hydration with runApp

Source: https://docs.jaspr.site/concepts/hydration

This code snippet demonstrates the basic setup for manual hydration in a Jaspr client entrypoint. It imports necessary Jaspr client libraries and the main application component, then uses `runApp` to attach and hydrate the `App` component to the 'body' element.

```dart
// Client-specific import
import 'package:jaspr/client.dart';

// Our main component
import 'lib/app.dart';

void main() {
  // Attaches the app component to the <body> tag
  // and hydrates the component / makes it interactive.
  runApp(App(), attachTo: 'body');
}

```

--------------------------------

### Define Custom Color Tokens (Dart)

Source: https://docs.jaspr.site/content/concepts/theming

Provides examples of defining custom ColorToken instances for specific branding or design elements, including light and dark mode variants.

```dart
final myCustomToken = ColorToken(
  'my-brand-accent', // CSS variable name will be --my-brand-accent
  ThemeColors.amber.$500,    // Light mode color
  dark: ThemeColors.amber.$400 // Dark mode color
);

final anotherToken = ColorToken('footer-bg', Color('#eeeeee')); // Same for light and dark
```

--------------------------------

### Add jaspr_content Package to Pubspec

Source: https://docs.jaspr.site/content/quick_start

This command adds the jaspr_content package as a dependency to your Jaspr project's pubspec.yaml file. This package is essential for handling and rendering content.

```dart
dart pub add jaspr_content
```

--------------------------------

### Example Rendered HTML for Document()

Source: https://docs.jaspr.site/api/components/document

Illustrates the resulting HTML output when using the `Document()` constructor with specific parameters like title and meta tags. This shows how the server-side Dart code translates into a complete HTML document.

```html
<!DOCTYPE html>
<html>
  <head>
    <base href="/"/>
    <meta charset="utf-8"/>
    <title>My Site</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <meta name="description" content="My site description"/>
  </head>
  <body>
    <div id="main"></div>
  </body>
</html>
```

--------------------------------

### Server / Client API Documentation

Source: https://docs.jaspr.site/api

This section includes utilities and classes for server-side rendering, client-side rendering, and interaction between the two.

```APIDOC
## Server / Client Utilities

### Description
Utilities and classes for server-side or client-side rendering, or the interaction between both.

### Method
N/A (Conceptual documentation)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Server / Client Utilities

- **@client**: Annotation for client-side specific code.
- **@encoder / @decoder**: Annotations for serialization/deserialization.
- **@Import**: Directive for importing resources.
- **@sync**: Annotation for synchronization mechanisms.
- **SyncStateMixin**: Mixin for state synchronization.
- **PreloadStateMixin**: Mixin for preloading state.
- **headers / setHeader()**: Access and set HTTP headers.
- **cookies / setCookie()**: Access and set cookies.
- **setStatusCode()**: Function to set the HTTP status code.
```

--------------------------------

### Define Static Routes with jaspr_router

Source: https://docs.jaspr.site/concepts/static_sites

Defines static routes for a Jaspr application using the `jaspr_router` package. This setup ensures all defined routes are rendered during the build process for static site generation. It includes example routes for the home, about, and contact pages.

```dart
Router(
  routes: [
    Route(path: '/', builder: (_, _) => HomePage()),
    Route(path: '/about', builder: (_, _) => AboutPage()),
    Route(path: '/contact', builder: (_, _) => ContactPage()),
  ]
);

```

--------------------------------

### RSS Output with Custom Page Filtering

Source: https://docs.jaspr.site/content/concepts/secondary_outputs

This snippet illustrates how to define a custom filter for RSSOutput to control which pages are included in the feed. The example shows a filter that includes only pages whose URLs start with '/posts'. Other filtering options like `optIn` and default inclusion are also mentioned.

```dart
RSSOutput(
  filter: RSSFilter.custom((Page page) {
    // Include only posts based on the page url. 
    return page.url.startsWith('/posts');
 }),
)

```

--------------------------------

### Integrate Dart Sass with Jaspr

Source: https://docs.jaspr.site/concepts/styling

This example shows how to integrate Dart Sass into a Jaspr project using the `sass_builder` package. First, create a `.scss` file with Sass code, potentially importing variables from other packages like `bootstrap_sass`. Then, include the generated CSS file as an external stylesheet in your Jaspr application.

```scss
@use "package:bootstrap_sass/scss/variables" as bootstrap;

.a {
  color: blue;
}
.c {
  color: bootstrap.$body-color;
}

```

```dart
link(rel:"stylesheet", href: "/styles.css")

```

--------------------------------

### ContentApp Constructors

Source: https://docs.jaspr.site/content/concepts/pages

Explains the different ways to instantiate and configure the ContentApp for managing website pages.

```APIDOC
## ContentApp Constructors

### Description
The `ContentApp` class provides constructors for creating `PageConfig` instances, allowing for site-wide or page-specific configurations.

### Method
N/A (Constructor)

### Endpoint
N/A

### Parameters
N/A (Methods of the ContentApp class)

#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```dart
// Creates a single PageConfig for all pages
final app = ContentApp(PageConfig(...)); 

// Creates a custom ConfigResolver function
final app = ContentApp.custom((page) => PageConfig(...));
```

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Migrating HTML Component Usage to New API

Source: https://docs.jaspr.site/releases/v/0.22

This example shows the migration of deprecated helper functions like `text()`, `fragment()`, and `raw()` to their new class-based equivalents (`Component.text()`, `Component.fragment()`, `RawText`). The new API supports dot-shorthands and `const` usage for improved performance and expressiveness.

```dart
// Before:
text('Hello World');
fragment([ ... ]);
raw('<div>Raw HTML</div>');

// After (with dot-shorthands):
.text('Hello World');
.fragment([ ... ]);
RawText('<div>Raw HTML</div>');

```

--------------------------------

### Success Callout Example

Source: https://docs.jaspr.site/content/components/callout

An example of using the `<Success>` callout variant to display a green box with a check icon. This is ideal for indicating a successful action.

```html
<Success>This draws attention to a successful action the user has taken.</Success>

```

--------------------------------

### Warning Callout Example

Source: https://docs.jaspr.site/content/components/callout

An example of using the `<Warning>` callout variant to display a yellow box with a warning icon. This is useful for alerting users about potential issues.

```html
<Warning>This draws attention to a warning they should take notice of.</Warning>

```

--------------------------------

### Add Flutter Support to GitHub Actions Workflow for Jaspr

Source: https://docs.jaspr.site/concepts/deploying

If your Jaspr project utilizes Flutter embedding or plugins, you need to include Flutter setup in your GitHub Actions workflow. Add the 'Setup Flutter' step after the 'Setup Dart' step to ensure Flutter is available during the build process. This prevents build errors related to missing Flutter environments.

```yaml
- name: 'Setup Flutter'
  uses: subosito/flutter-action@v2
```

--------------------------------

### Initialize Client Logic in @client Component

Source: https://docs.jaspr.site/api/utils/at_client

Shows how to initialize client-side logic within a @client component by using the initState() method. This is useful for setting up service locators, plugins, or global state, with an option to skip execution on the server using kIsWeb.

```dart
@override
void initState() {
    super.initState();
    // Optionally skip the initialization logic on the server.
    if (kIsWeb) {
      // Your initialization logic, e.g. for setting up service locators, plugins or other global state.
    }
}
```

--------------------------------

### Install Tailwind CLI

Source: https://docs.jaspr.site/eco/tailwind

Installs the standalone Tailwind CLI for use with Jaspr. Download the appropriate executable for your platform, make it executable, and move it to a location in your system's PATH.

```bash
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-<your-platform>
chmod +x tailwindcss-<your-platform>

# e.g. /usr/local/bin on unix based systems (linux, macos)
mv tailwindcss-<your-platform> /usr/local/bin/tailwindcss

tailwindcss -h
```

--------------------------------

### JasprBadge Backlinking Example

Source: https://docs.jaspr.site/api/components/jaspr_badge

Shows how to wrap the JasprBadge component within an anchor tag to create a backlink to the official Jaspr website. This is recommended for promoting Jaspr. It utilizes the 'a' tag component and 'Target.blank' for opening the link in a new tab.

```dart
a(href: 'https://jaspr.site', target: Target.blank, [
  JasprBadge.light(),
]);
```

--------------------------------

### Client Entrypoint: Selective Hydration with SlottedChildView

Source: https://docs.jaspr.site/concepts/hydration

This example shows how to achieve selective manual hydration using `SlottedChildView` and `ChildSlot.fromQuery`. It targets specific HTML elements by CSS selectors ('header', '#sidebar', '#content') and attaches corresponding Jaspr components, allowing other parts of the page to remain static.

```dart
void main() {
  runApp(SlottedChildView(slots: [
    ChildSlot.fromQuery('header', child: Header()),
    ChildSlot.fromQuery('#sidebar', child: Sidebar()),
    ChildSlot.fromQuery('#content', child: Content()),
  ]));
}

```

--------------------------------

### Error Callout Example

Source: https://docs.jaspr.site/content/components/callout

An example of using the `<Error>` callout variant to display a red box with an error icon. This is best for highlighting critical errors users might encounter.

```html
<Error>This draws attention to an error the user might run into if they don't pay attenion.</Error>

```

--------------------------------

### Define Basic Routes with Jaspr Router

Source: https://docs.jaspr.site/api/components/router

Configures the main application router with multiple routes, mapping URL paths to corresponding page components. This example demonstrates setting up the root path and an about page.

```dart
import 'package:jaspr_router/jaspr_router.dart';

import 'pages/home.dart';
import 'pages/about.dart';

class App extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return Router(routes: [
      Route(path: '/', builder: (context, state) => Home()),
      Route(path: '/about', builder: (context, state) => About()),
    ]);
  }
}
```

--------------------------------

### General Utilities

Source: https://docs.jaspr.site/api/utils/run_app

Documentation for general Jaspr utilities, including Styles, @css, events(), GlobalNodeKey, and ViewTransitionMixin.

```APIDOC
## General Jaspr Utilities

### Utilities Overview
General utilities for styling, event handling, and key management.

- **Styles**: Utility for creating and managing CSS styles.
- **@css / css()**: Annotations or functions for CSS definitions.
- **events()**: Function to handle events.
- **GlobalNodeKey**: For global key management of nodes.
- **ViewTransitionMixin**: Mixin for managing view transitions.
```

--------------------------------

### Jaspr ElementNode and TextNode Example (Python)

Source: https://docs.jaspr.site/content/concepts/page_parsing

Demonstrates the creation of a nested structure using Jaspr's ElementNode and TextNode to represent a styled paragraph. This example shows how to combine text and nested elements to form complex content structures. ElementNode takes a tag name, attributes, and a list of children, while TextNode represents plain text.

```python
ElementNode('p', {'class': 'intro'}, [
  TextNode('This is a '),
  ElementNode('strong', {}, [TextNode('paragraph')]),
  TextNode(' with styling.'),
])
```

--------------------------------

### Jaspr Component with Tailwind Classes

Source: https://docs.jaspr.site/eco/tailwind

Example of a Jaspr `StatelessComponent` (`SimpleCard`) that utilizes Tailwind CSS classes for styling its elements.

```dart
import 'package:jaspr/jaspr.dart';

class SimpleCard extends StatelessComponent {
  const SimpleCard({required this.title, required this.message});

  final String title;
  final String message;

  @override
  Component build(BuildContext context) {
    return div(classes: 'p-6 max-w-sm mx-auto bg-white rounded-xl shadow-lg flex items-center space-x-4', [
      div(classes: 'shrink-0', [
        img(classes: 'h-12 w-12', src: '/img/logo.svg', alt: '$title Logo'),
      ]),
      div([
        div(classes: 'text-xl font-medium text-black', [.text(title)]),
        p(classes: 'text-slate-500', [.text(message)]),
      ])
    ]);
  }
}
```

--------------------------------

### Implement Custom Template Engine Interface

Source: https://docs.jaspr.site/content/concepts/templating

Provides an example of creating a custom template engine by implementing the `TemplateEngine` interface. This allows for custom templating logic or preprocessing of content before it's applied to the page.

```dart
class CustomTemplateEngine implements TemplateEngine {
  @override
  Future<void> render(Page page, List<Page> pages) async {
    // 1. Access page content with page.content
    final content = page.content;
    
    // 2. Process the content with your templating logic
    final processedContent = myTemplateProcessingFunction(content, page.data, pages);
    
    // 3. Update the page content
    page.apply(content: processedContent);
  }
}


```

--------------------------------

### Configure ContentApp with Parsers

Source: https://docs.jaspr.site/content/concepts/page_parsing

Example of configuring the ContentApp with built-in Markdown and HtmlParser to handle different file types in the content directory.

```dart
ContentApp(
  parsers: [
    MarkdownParser(),
    HtmlParser(),
  ],
)
```

--------------------------------

### Add flutter_embed_component Dependency

Source: https://docs.jaspr.site/going_further/flutter_embedding

Installs the necessary package for embedding Flutter web apps into Jaspr. This is a prerequisite for using the FlutterEmbedView component.

```dart
dart pub add flutter jaspr_flutter_embed
```

--------------------------------

### Implement PreloadStateMixin for Server-Side State Preloading

Source: https://docs.jaspr.site/api/utils/preload_state_mixin

This snippet demonstrates how to integrate the PreloadStateMixin into a StatefulComponent's State class. The `preloadState` method is executed on the server before `initState` to asynchronously fetch data, deferring the component's initialization and rendering until the data is ready.

```dart
class MyStatefulComponent extends StatefulComponent {
  /* ... */ 
}

class MyState extends State<MyStatefulComponent> with PreloadStateMixin {

  @override
  Future<void> preloadState() async {
    /* ... perform asynchronous data fetching here ... */ 
  }
}
```

--------------------------------

### Responsive Styles with Media Queries

Source: https://docs.jaspr.site/concepts/styling

Implements responsive design by applying different styles based on screen characteristics using `css.media()`. This utility generates CSS `@media` queries, allowing layouts to adapt to various screen sizes.

```dart
@css
List<StyleRule> get styles => [
    css('.main').styles(
      display: Display.flex, 
      flexDirection: FlexDirection.row,
    ),
    css.media(MediaQuery.screen(maxWidth: 600.px), [
      css('.main').styles(
        flexDirection: FlexDirection.column,
      ),
    ]),
];

```

--------------------------------

### Configuring Collapsible Folders in FileTree

Source: https://docs.jaspr.site/content/components/file_tree

This example illustrates how to specify which folders should be collapsed by default in the FileTree component by prefixing the folder name with a '^' character.

```markdown
<FileTree>

- lib/ // This folder will be open by default
  - ^src/ // This folder will be closed by default
    - utils.dart
  - main.dart
- README.md

</FileTree>

```

--------------------------------

### Components API Documentation

Source: https://docs.jaspr.site/api

This section provides an overview of relevant components in the core Jaspr framework.

```APIDOC
## Components

### Description
Overview of relevant components in the core Jaspr framework.

### Method
N/A (Conceptual documentation)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Core Components

- **Document**: Represents the HTML document structure.
- **RawText**: Component for rendering raw text.
- **AsyncBuilder**: Component for building UI asynchronously.
- **AsyncStatelessComponent**: Async version of a stateless component.
- **Router**: Component for handling client-side routing.
- **Link**: Component for creating navigation links.
- **Style**: Component for applying styles.
- **FlutterEmbedView**: Component for embedding Flutter content.
- **JasprBadge**: Component for displaying badges.
```

--------------------------------

### Client Initialization with ClientApp Component

Source: https://docs.jaspr.site/releases/v/0.22

This snippet demonstrates the new structure for `main.client.dart` in Jaspr version 0.22.0. It initializes the Jaspr application and wraps the `ClientApp` component, which is responsible for initializing `@client` components. The `ClientApp` can be further wrapped to share state or perform custom initialization.

```dart
// Previously 'browser.dart', now renamed.
import 'package:jaspr/client.dart';

// Generated options file.
import 'main.client.options.dart';

void main() {
  Jaspr.initializeApp(
    options: defaultClientOptions,
  );

  runApp(
    // New component to initialize @client components.
    const ClientApp(),
  );
}

```

--------------------------------

### Configure ContentTheme Fonts (Dart)

Source: https://docs.jaspr.site/content/concepts/theming

Illustrates how to specify default and code-specific font families for the site using ContentTheme. If not provided, default fonts are used.

```dart
ContentTheme(
  font: FontFamilies.arial,
  codeFont: FontFamily('SomeMonoFont')
)
```