Asgaard MD

A Svelte library for parsing and rendering Markdown content using custom Svelte components. This library allows users to display Markdown in a structured and customizable way, with the ability to edit the content directly and override individual rendering components.

Purpose

The goal of Asgaard MD is to provide a flexible and extensible Svelte component that:

• Parses Markdown content and renders it using custom Svelte components.
• Allows users to edit the Markdown content directly within the application.
• Supports overriding individual rendering components for full customization.
• Handles nested structures like task lists and other complex Markdown elements.

Scope

• Input: Accept Markdown content as a string or file path.
• Output: Render the parsed Markdown using custom Svelte components.
• Features: Support for headings, lists, task lists (including nested task lists), links, images, code blocks, and basic formatting.
• Customization: Allow users to override default styles, behaviors, and individual rendering components via props.
• Editing: Enable users to edit the Markdown content directly.

Features

• Parse and render Markdown using remark-parse to generate an AST.
• Custom Svelte components for each Markdown element.
• Component hierarchy builder to traverse the AST and map nodes to Svelte components.
• Support for nested task lists and other complex structures.
• Full customization via props and component overrides.

Installation

To install Asgaard MD, run:

npm install asgaard-md

Usage

Here's a basic example of how to use Asgaard MD in your Svelte application:

<script>
  import { Markdown } from "asgaard-md";

  let markdownContent = "# Hello, World!\n\nThis is **bold** text.";
</script>

<Markdown {markdownContent} />

Documentation

For more details on how to use and customize Asgaard MD, refer to the SPECIFICATIONS.md file.

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

# create a new project in the current directory
npx sv create

# create a new project in my-app
npx sv create my-app

To recreate this project with the same configuration:

# recreate this project
npx sv create --template library --types ts --add prettier --install npm .

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Everything inside src/lib is part of your library, everything inside src/routes can be used as a showcase or preview app.

Building

To build your library:

npm pack

To create a production version of your showcase app:

npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment.

Publishing

Go into the package.json and give your package the desired name through the "name" option. Also consider adding a "license" field and point it to a LICENSE file which you can create from a template (one popular option is the MIT license).

To publish your library to npm:

npm publish