npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

svelte-simple-markdown

v1.0.3

Published

Simple and Extensible Markdown Parser for any framework.

Downloads

10

Readme

svelte-simple-markdown

This is a fork of Simple-Markdown, modified to target Svelte, however due to separating the parsing and outputting steps, it can be used to target any web framework.

Philosophy

Most markdown-like parsers aim for speed or edge case handling. simple-markdown aims for extensibility and simplicity.

What does this mean? Many websites using markdown-like languages have custom extensions, such as @mentions or issue number linking. Unfortunately, most markdown-like parsers don't allow extension without forking, and can be difficult to modify even when forked. svelte-simple-markdown is designed to allow simple addition of custom extensions without needing to be forked.

At Khan Academy, the original simple-markdown is used to format over half of their math exercises, because markdown extensions for math text and interactive widgets are necessary.

On davecode.net, I use the svelte version to format custom content within my Input & Output page.

Getting started

This module is only distributed as ES Modules, so you'll want to be using SvelteKit or Vite for your codebase.

The first step is to create a parser and config object. You should do this in a file outside your svelte components, so the markdown configuration is only created once, and can be reused around your codebase.

import { createParser, defaultRules } from 'svelte-simple-markdown';

const parser = createParser(defaultRules);

export const markdownConfig = {
	parser
};

To add your own extensions, you just have to clone() the default rule list and add your own. You'll find that defaultRules is a custom RuleList class which has some helper methods. In this example, we add a basic issue number type.

import { createParser, defaultRules } from 'svelte-simple-markdown';
import IssueLink from '$lib/components/IssueLink.svelte';

const customRules = defaultRules.clone();

customRules.insertBefore('em', {
	name: 'issue',
	match: inlineRegex(/^#(\d+)/),
	parse(capture) {
		return {
			number: capture[1]
		};
	}
});

const parser = createParser(customRules);

export const markdownConfig = {
	parser,
	renderers: {
		issue: IssueLink
	}
};

The "before" of insertBefore refers to the parsing priority.

Custom Renderers are simply Svelte components given a node prop of the ast node. If your node has a content property, it is rendered into your renderer's <slot />.

<script lang="ts">
	import type { ASTNode } from '$lib/core';

	export let node: ASTNode;
</script>

<a sveltekit:prefetch href="/issues/{node.id}">
	#{node.id}
</a>

The Markdown svelte component can now display any markdown string.

<script lang="ts">
	import { Markdown } from 'svelte-simple-markdown';
	import { markdownConfig } from '$lib/markdown';
</script>

<Markdown config={markdownConfig} value="Hello **World**, see #54!" />

Other Frameworks

You'll find non-svelte related code (all parsing and default rules) in svelte-simple-markdown/core. To use this with other frameworks, you'll have to write your own renderer. If you do that, please get in touch with an issue and we could try and organise this as a multi-framework markdown project.

Extension Overview

Elements in simple-markdown are generally created from rules. For parsing, rules must specify match and parse methods. For output, rules must specify a react or html method (or both), depending on which outputter you create afterwards.

Here is an example rule, a slightly modified version of what simple-markdown uses for parsing strong (bold) text:

rules.add({
	name: 'strong',
	match(source, state, lookbehind) {
		return /^\*\*([\s\S]+?)\*\*(?!\*)/.exec(source);
	},
	parse(capture, recurseParse, state) {
		return {
			content: recurseParse(capture[1], state)
		};
	}
});

Let's look at those methods in more detail.

match(source: string, state: ParserState)

simple-markdown calls your match function to determine whether the upcoming markdown source matches this rule or not.

source is the upcoming source, beginning at the current position of parsing (source[0] is the next character).

state is a mutable state object to allow for more complicated matching and parsing. The most common field on state is inline, which all of the default rules set to true when we are in an inline scope, and false or undefined when we are in a block scope.

state.lookbehind is the string previously captured at this parsing level, to allow for lookbehind. For example, lists check that lookbehind ends with /^$|\n *$/ to ensure that lists only match at the beginning of a new line.

If this rule matches, match should return an object, array, or array-like object, which we'll call capture, where capture[0] is the full matched source, and any other fields can be used in the rule's parse function. The return value from Regexp.prototype.exec fits this requirement, and the common use case is to return the result of someRegex.exec(source).

If this rule does not match, match should return null.

NOTE: If you are using regexes in your match function, your regex should always begin with ^. Regexes without leading ^s can cause unexpected output or infinite loops.

parse(capture: Capture, recurseParse: Parser, state: ParserState)

parse takes the output of match and transforms it into a syntax tree node object, which we'll call node here.

capture is the non-null result returned from match.

recurseParse is a function that can be called on sub-content and state to recursively parse the sub-content. This always returns an array.

state is the mutable state threading object, which can be examined or modified, and should be passed as the second argument to any recurseParse calls.

For example, to parse inline sub-content, you can add inline: true to state, or inline: false to force block parsing (to leave the parsing scope alone, you can just pass state with no modifications). For example:

const innerText = capture[1];
recurseParse(
	innerText,
	_.defaults(
		{
			inline: true
		},
		state
	)
);

parse should return a node object, which can have custom fields that will be passed to output, below. The one reserved field is type, which designates the type of the node, which will be used for output. If no type is specified, simple-markdown will use the current rule's type (the common case). If you have multiple ways to parse a single element, it can be useful to have multiple rules that all return nodes of the same type.