Quick Start

Setup

To get started, 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.

Then perform the following steps:

• Add jaspr_content

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

  dart pub add jaspr_content
  

• 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.

  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   |
  

• Update main.dart

  Remove all files in lib/ except for main.dart and jaspr_options.dart.

  Open the lib/main.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.dart with the following code:

  lib/main.dart

  import 'package:jaspr/jaspr.dart';
  import 'package:jaspr_content/jaspr_content.dart';
  
  import 'jaspr_options.dart';
  
  void main() {
    Jaspr.initializeApp(options: defaultJasprOptions);
  
    runApp(ContentApp(
      parsers: [
        MarkdownParser(),
      ],
    ));
  }
  

• Launch Jaspr

  Launch your Jaspr application using either the VSCode extension or the jaspr serve command in your terminal.

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 to add a title, meta tags or any other data to your pages.

  content/index.md

  ---
  title: My Page Title
  description: My Page Description
  ---
  
  ...
  

• Add one of the provided layouts or create your own. For example, DocsLayout provides a beautiful documentation layout with a header, sidebar and table of contents (Similar to the docs you are reading right now).

  lib/main.dart

  layouts: [
    DocsLayout()
  ],
  

• Use custom components like Callout or CodeBlock in your content files.

  lib/main.dart

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

  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 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.

  lib/main.dart

  templateEngine: MustacheTemplateEngine(),
  

  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:

  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:

  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 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 checkout their respective code documentation for more details.

• ContentApp: The main entry point for setting up a content-driven site.
• Page: 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: 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: Loads pages from a sources like the filesystem or a github repository.
• DataLoader: Loads additional data from sources like .json or .yaml files.
• TemplateEngine: 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: Parses the content from a file format like markdown or html.
• PageExtension: 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: A custom component that can be used in content files. This allows you to use Jaspr components in your content files.
• PageLayout: 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: 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: Defines a secondary output for a page. This may be used for outputting supplementary files like a 'index.html.md' file containing the raw markdown of a page.