---
title: Quick Start
description: Get started with jaspr_content to build content-driven sites.
---

---

## Setup

### Documentation Template

To get you started quickly, Jaspr comes with a new **Documentation Template** you can choose when creating a new project. This will give you an already functional documentation site out-of-the-box with no manual setup.

To use this template, either select it when creating a new project using the **Jaspr VSCode Extension**, or run:

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

### Custom Setup

If the template isn't the right fit for you, it's also very easy to get started with a custom setup. To do this, perform the following steps:

<Steps>
  <Step title="Create a new Project">

    Create a new Jaspr project in either `static` or `server` mode.

    You can do this using the **Jaspr VSCode extension** or by using the `jaspr create` command.
  </Step>
  <Step title="Add jaspr_content">

    Add the `jaspr_content` package to your project by adding it to your `pubspec.yaml` file:

    ```shell
    dart pub add jaspr_content
    ```
  </Step>
  <Step title="Add a Content Directory">

    Create a top-level `content/` directory in your project. This is where you will store your content files. Inside the `content/` directory, create a new file called `index.md` and add some sample content.

    ````markdown title="content/index.md"
    # 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   |
    ````

  </Step>
  <Step title="Update main.server.dart">

    Remove all files in `lib/` except for `main.server.dart` and `main.server.options.dart`.

    Open the `lib/main.server.dart` file in your project. This is where you will set up the `jaspr_content` package to load and render your content.

    Replace the contents of `lib/main.server.dart` with the following code:

    ```dart title="lib/main.server.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(),
        ],
      ));
    }
    ```
  </Step>
  <Step title="Launch Jaspr">
    Launch your Jaspr application using either the VSCode extension or the `jaspr serve` command in your terminal.
  </Step>
</Steps>

<Success>
  This minimal setup already gives you a functional markdown rendering system in your Jaspr application. You can try around with editing your markdown and adding more content files.
</Success>

## Explore More

So far we have only seen a very minimal setup for `ContentApp` and there is lots more to discover. For example:

- You can use [Frontmatter](/content/guides/writing_content#frontmatter) to add a title, meta tags or any other data to your pages.

  ```markdown title="content/index.md"
  ---
  title: My Page Title
  description: My Page Description
  ---

  // ...
  ```

- Add one of the provided [layouts](/content/concepts/page_layouts) or create your own. For example, [DocsLayout](/content/layouts/docs_layout) provides a beautiful documentation layout with a header, sidebar and table of contents *(Similar to the docs you are reading right now)*.

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

- Use custom components like [Callout](/content/components/callout) or [CodeBlock](/content/components/code_block) in your content files.

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

  ````markdown title="content/index.md"
  You can use Jaspr components in your content files using their "html" syntax:

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

  Or components can override existing markdown blocks, like how the `CodeBlock`
  component adds **syntax highlighting** and a **copy button** to standard code blocks:

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

  You can also add [**your own Jaspr components**](/content/concepts/custom_components) and use them in your content files.

- Add a template engine like `MustacheTemplateEngine` to enable using a templating syntax in your markdown files. This allows you to use variables and conditionals in your content.

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

  ```markdown title="content/index.md"
  ---
  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}}
  ```

  In addition to Frontmatter data, you can also use data from JSON or YAML files in the `content/_data` directory. For example, if you have a `content/_data/faq.yaml` file with the following content:

  ```yaml title="content/_data/faq.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).
  ```

  You can access this data in your markdown files using the `faq` variable:

  ```markdown title="content/index.md"
  ---
  title: FAQ
  ---

  # Frequently Asked Questions

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

---

## Guides

This still only scratches the surface of what is possible with `jaspr_content`. Almost every part of the content rendering process can be customized and extended. You can switch out any part of the process independently, configure it to your liking, or extend it with your own custom implementation.

Check out the [**Guides**](/content/guides/adding_pages) section for a full walkthrough of all the features and how to use them.

## Concepts

If you want to make sure to understand all concepts, here is a full list of all major parts and their purpose. Also, check out their respective code documentation for more details.

- [**ContentApp**](/content/concepts/content_app): The main entry point for setting up a content-driven site.
- [**Page**](/content/concepts/pages): A data object that holds all information and configuration about a single page. A page is what will be rendered to a `.html` file.
- [**PageConfig**](/content/concepts/pages#pageconfig): A configuration object that holds all settings for parsing and rendering content. This may either be applied to a single page (where different pages have different PageConfigs) or to the whole app.
- [**RouteLoader**](/content/concepts/route_loading): Loads pages from sources like the filesystem or a GitHub repository.
- [**DataLoader**](/content/concepts/data_loading): Loads additional data from sources like `.json` or `.yaml` files.
- [**TemplateEngine**](/content/concepts/templating): Pre-processes the content using a templating language like mustache. This is useful for injecting data (from frontmatter and data loaders) into the content before parsing.
- [**PageParser**](/content/concepts/page_parsing): Parses the content from a file format like markdown or HTML.
- [**PageExtension**](/content/concepts/page_extensions): Post-processes a page after parsing. This may analyze and modify the page in many different ways and is useful for adding features like custom components or a table of contents.
- [**CustomComponent**](/content/concepts/custom_components): A custom component that can be used in content files. This allows you to use Jaspr components in your content files.
- [**PageLayout**](/content/concepts/page_layouts): Renders a page's content into a final HTML layout. This may include any additional ui elements like a header, sidebar, or footer. Multiple layouts are supported, and a page may choose a different layout than the default one.
- [**ContentTheme**](/content/concepts/theming): Defines the theme colors and typographic styles for the site. This includes primary and background colors, light and dark variants as well as font sizes and styles for headers, paragraphs and more.
- [**SecondaryOutput**](/content/concepts/secondary_outputs): Defines a secondary output for a page. This may be used for outputting supplementary files like an 'index.html.md' file containing the raw markdown of a page.