mdsvex

https://mdsvex.pngwn.io/docs
Admin
mdsvex is a markdown preprocessor for Svelte components, allowing the use of Svelte components...
Tokens:5,174
Snippets:38
Trust Score:4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install mdsvex with npm

Source: https://mdsvex.pngwn.io/docs/index

Installs mdsvex as a development dependency using npm.

```bash
npm i -D mdsvex
```

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

### Install mdsvex with yarn

Source: https://mdsvex.pngwn.io/docs/index

Installs mdsvex as a development dependency using yarn.

```bash
yarn add --dev mdsvex
```

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

### TOML Frontmatter Example

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates writing frontmatter in TOML format using a custom triple-plus marker.

```toml
+++
title = "TOML Example"

[owner]
name = "some name"
dob = 1879-05-27T07:32:00-08:00
+++
```

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

### Svelte Layout Component Example

Source: https://mdsvex.pngwn.io/docs/index

A Svelte component example for an Mdsvex layout, receiving props like 'title', 'author', and 'date' from frontmatter and rendering the main content via a slot.

```svelte
<script>
  export let title;
  export let author;
  export let date;
</script>

<h1>{ title }</h1>
<p class="date">on: { date }</p>
<p class="date">by: { author }</p>
<slot>
  <!-- the mdsvex content will be slotted in here -->
</slot>
```

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

### mdsvex Frontmatter Example

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates using frontmatter variables within markdown content.

```markdown
---
title: Fabuloso
---

# {title}
```

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

### Mdsvex: YAML Frontmatter Example

Source: https://mdsvex.pngwn.io/docs/index

Shows a basic example of using YAML frontmatter in Mdsvex to define metadata such as 'title' and 'author', which are directly accessible within the component.

```yaml
---
title: My lovely article
author: Dr. Fabuloso the Fabulous
---
```

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

### mdsvex Layout Example: Named Layout

Source: https://mdsvex.pngwn.io/docs/index

Specifies a named layout ('blog') for an mdsvex document using frontmatter.

```markdown
---
layout: blog
---


```

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

### Mdsvex Frontmatter Configuration

Source: https://mdsvex.pngwn.io/docs/index

Configure Mdsvex to use custom frontmatter markers and parsing functions. Supports YAML by default, with examples for custom markers and TOML parsing.

```javascript
frontmatter: { parse: Function, marker: string };

marker: string = '-';
```

```javascript
mdsvex({
	frontmatter: {
		marker: "+"
	}
});
```

```javascript
parse: (frontmatter, messages) => Object | undefined
```

```javascript
mdsvex({
	marker: "+",
	parse(frontmatter, messages) {
		try {
			return toml.parse(frontmatter);
		} catch (e) {
			messages.push(
				"Parsing error on line " +
					e.line +
					", column " +
						e.column +
						": " +
							e.message
			);
		}
	}
});
```

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

### mdsvex Layout Example: Disable Layout

Source: https://mdsvex.pngwn.io/docs/index

Disables named layouts for an mdsvex document by setting layout to false in frontmatter.

```markdown
---
layout: false
---


```

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

### MDSVEX Indentation Limitation Example

Source: https://mdsvex.pngwn.io/docs/index

Illustrates a limitation in MDSVEX where indenting fenced code blocks (e.g., with 4 spaces) can cause unexpected rendering issues. The recommended solution is to avoid indenting fenced code blocks.

```text
		```js
					console.log('Hello, World!')
		```

```

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

### Importing Markdown as a Svelte Component

Source: https://mdsvex.pngwn.io/docs/index

Illustrates how to import a Markdown file (e.g., 'readme.md') as a Svelte component and render it within a Svelte application.

```svelte
<script>
  import Readme from '../readme.md'
</script>

<Readme />

```

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

### Mdsvex Configuration for Markdown Files

Source: https://mdsvex.pngwn.io/docs/index

Shows how to configure mdsvex to process both .svx and .md files, and how to add .md to the Svelte compiler extensions for importing Markdown files as Svelte components.

```javascript
// svelte.config.js
import { mdsvex } from 'mdsvex'

export default {
  extensions: ['.svelte', '.svx', '.md'],
  preprocess: mdsvex({ extensions: ['.svx', '.md'] }),
}
```

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

### Compile mdsvex directly with Svelte Compiler

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates using mdsvex with Svelte's preprocess function directly, bypassing bundlers.

```javascript
const svelte = require('svelte/compiler');
const { mdsvex } = require('mdsvex');

// This will give you a valid svelte component
const preprocessed = await svelte.preprocess(
	source,
	mdsvex(mdsvex_opts)
);

// Now you can compile it if you wish
const compiled = svelte.compile(
	preprocessed,
	compiler_options
);

```

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

### mdsvex with Svelte Components

Source: https://mdsvex.pngwn.io/docs/index

Shows how to import and use Svelte components within an mdsvex document.

```markdown
<script>
	import { Chart } from "../components/Chart.svelte";
</script>

# Here’s a chart

The chart is rendered inside our MDsveX document.

<Chart />

```

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

### Integrate Shiki Highlighter in MDSVEX

Source: https://mdsvex.pngwn.io/docs/index

Shows how to configure MDSVEX to use the shiki library for code highlighting instead of Prism. It involves creating a shiki highlighter instance with specified themes and languages, and then using it within the mdsvexOptions.

```javascript
import { mdsvex, escapeSvelte } from 'mdsvex';
import { createHighlighter } from 'shiki';

const theme = 'github-dark';
const highlighter = await createHighlighter({
	tthemes: [theme],
	langs: ['javascript', 'typescript']
});

/** @type {import('mdsvex').MdsvexOptions} */
const mdsvexOptions = {
	highlight: {
		highlighter: async (code, lang = 'text') => {
			const html = escapeSvelte(highlighter.codeToHtml(code, { lang, theme }));
			return `{@html `${html}` }`;
		}
	},
}

```

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

### Mdsvex: Render Custom Components

Source: https://mdsvex.pngwn.io/docs/index

Illustrates how custom components exported from a layout's module context are imported and used to render specific HTML elements within the Svelte component.

```svelte
<script>
  import * as Components from './Layout.svelte';
</script>

<Components.h1>Title</Components.h1>
<Components.p>Some text</Components.p>
<ul>
  <Components.li>a</Components.li>
  <Components.li>short</Components.li>
  <Components.li>list</Components.li>
</ul>
```

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

### Mdsvex: Custom Image Component with Attributes

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates how to create a custom image component in Mdsvex that accepts and renders attributes like 'src', allowing for custom image handling.

```svelte
<script>
  export let src;
</script>

<img src={src} />
```

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

### Mdsvex Smartypants Options

Source: https://mdsvex.pngwn.io/docs/index

Defines the structure for the `smartypants` option in mdsvex, which can be a boolean or an object with specific configurations for typographic transformations.

```javascript
smartypants: boolean | {
	quotes: boolean = true;
	ellipses: boolean = true;
	backticks: boolean | 'all' = true;
	dashes: boolean | 'oldschool' | 'inverted' = true;
} = true;
```

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

### Configure Svelte for mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Configures the Svelte preprocessor to handle .svx files using mdsvex.

```javascript
svelte({
  extensions: [
    '.svelte',
    '.svx'
  ],
  preprocess: mdsvex(config)
})
```

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

### Smartypants Dashes Transformation

Source: https://mdsvex.pngwn.io/docs/index

Explains the `dashes` option within `smartypants`, which controls the conversion of double and triple dashes into em-dashes or en-dashes based on the specified mode.

```javascript
dashes: boolean | 'oldschool' | 'inverted' = true;

// When `true`, converts two dashes into an em-dash character.
//  * `--` **becomes** —


// When `'oldschool'`, converts two dashes into an en-dash, and three dashes into an em-dash.
//  * `--` **becomes** –
//  * `---` **becomes** —


// When `'inverted'`, converts two dashes into an em-dash, and three dashes into an en-dash.
//  * `--` **becomes** —
//  * `---` **becomes** –
```

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

### Mdsvex Layout Configuration

Source: https://mdsvex.pngwn.io/docs/index

Configure Mdsvex to use a Svelte component as a layout for markdown content. Layouts receive frontmatter variables as props.

```javascript
mdsvex({
	layout: "./path/to/layout.svelte"
});
```

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

### Smartypants Quotes Transformation

Source: https://mdsvex.pngwn.io/docs/index

Explains the `quotes` option within `smartypants`, which converts straight double and single quotes to their typographic equivalents.

```javascript
quotes: boolean = true;

// Converts straight double and single quotes to smart double or single quotes.
//  * "words" **becomes** : “words”
//  * 'words' **becomes** ‘words’
```

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

### TypeScript Ambient Module Declaration for Markdown

Source: https://mdsvex.pngwn.io/docs/index

Provides a TypeScript ambient module declaration for '*.md' files, allowing Markdown files to be imported as Svelte components and exposing their metadata.

```typescript
declare module '*.md' {
	import type { SvelteComponent } from 'svelte'

	export default class Comp extends SvelteComponent {}

	export const metadata: Record<string, unknown>
}
```

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

### Compile mdsvex code to Svelte

Source: https://mdsvex.pngwn.io/docs/index

Uses the 'compile' export from mdsvex to transform mdsvex source code into Svelte code.

```javascript
import { compile } from 'mdsvex';

const transformed_code = await compile(`
<script>
  import Chart from './Chart.svelte';
</script>


```

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

### Smartypants Backticks Transformation

Source: https://mdsvex.pngwn.io/docs/index

Describes the `backticks` option within `smartypants`, which handles the conversion of double backticks and straight single quotes into smart quotes.

```javascript
backticks: boolean | 'all' = true;

// When `true`, converts double back-ticks into an opening double quote, and double straight single quotes into a closing double quote.
//  * `words''` **becomes** “words”


// When `'all'` it also converts single back-ticks into a single opening quote, and a single straight quote into a closing single, smart quote.
// Note: Quotes can not be `true` when backticks is `'all'`;
```

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

### Configure Rollup for mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Integrates mdsvex into a Rollup build process using rollup-plugin-svelte.

```javascript
import { mdsvex } from "mdsvex";

export default {
	...boring_config_stuff,
	plugins: [
		svelte({
			// these are the defaults. If you want to add more extensions, see https://mdsvex.pngwn.io/docs#extensions
			extensions: [".svelte", ".svx"],
			preprocess: mdsvex()
		})
	]
};

```

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

### Mdsvex: Configure Named Layouts

Source: https://mdsvex.pngwn.io/docs/index

Configure Mdsvex to use different Svelte layout files for different document types by providing an object of named layouts. A fallback layout can be specified using the '_' key.

```javascript
mdsvex({
	layout: {
		blog: "./path/to/blog/layout.svelte",
		article: "./path/to/article/layout.svelte",
		"_": "./path/to/fallback/layout.svelte"
	}
});
```

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

### Configure Webpack for mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Integrates mdsvex into a Webpack build process using svelte-loader.

```javascript
const { mdsvex } = require('mdsvex')

// add ".svx" to the extensions array
const extensions = ['.mjs', '.js', '.json', '.svelte', '.html', '.svx'];

module.exports = {
	...boring_config_stuff,
	resolve: { alias, extensions, mainFields },
	module: {
		rules: [
			{
				// tell svelte-loader to handle svx files as well
				test: /.(svelte|html|svx)$/,
				use: {
					loader: 'svelte-loader',
					options: {
						...svelte_options,
						preprocess: mdsvex()
					}
				}
			}
		]
	}
};

```

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

### Mdsvex: Specify Layout in Frontmatter

Source: https://mdsvex.pngwn.io/docs/index

Manually assign a layout to a specific Mdsvex file by declaring the desired layout name in the frontmatter using the 'layout' key.

```yaml
---
layout: blog
---
```

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

### Add Remark and Rehype Plugins to Mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Integrate remark and rehype plugins to process Markdown AST (MDAST) and HTML AST (HAST) respectively. Plugins can be added directly or with options.

```javascript
import containers from "remark-containers";
import github from "remark-github";

mdsvex({
	remarkPlugins: [containers, github]
});
```

```javascript
import containers from "remark-containers";
import github from "remark-github";

mdsvex({
	remarkPlugins: [
		[containers, container_opts],
		[github, github_opts]
	]
});
```

```javascript
import containers from "remark-containers";
import github from "remark-github";

mdsvex({
	remarkPlugins: [
		[containers, container_opts],
		github,
		another_plugin,
		[yet_another_plugin, more_options]
	]
});
```

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

### Mdsvex Configuration with Custom Extensions

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates how to configure mdsvex with custom file extensions in a Svelte project using rollup-plugin-svelte. It shows how to specify extensions for both Svelte compilation and mdsvex preprocessing.

```javascript
export default {
	...config,
	plugins: [
		svelte({
			extensions: [".svelte", ".custom"],
			preprocess: mdsvex({
				extensions: [".custom"]
			})
		})
	]
};
```

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

### Export Metadata from MDSVEX Module

Source: https://mdsvex.pngwn.io/docs/index

Demonstrates how to export variables like title and author as a single 'metadata' object from a 'context="module"' script in MDSVEX. This allows for easy import into JavaScript files.

```svelte
<script context="module">
  export let metadata = {
    title: "My lovely article",
    author: "Dr. Fabuloso the Fabulous"
  };
</script>

```

```javascript
import { metadata } from "./some-mdsvex-file.svx";

```

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

### Configure Custom Syntax Highlighting in Mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Customize code highlighting in mdsvex by providing a custom highlighter function or defining language aliases. PrismJS is used by default.

```javascript
mdsvex({
	highlight: {
		alias: { yavascript: "javascript" }
	}
})
```

```javascript
function highlighter(code, lang) {
	return `<pre><code>${code}</code></pre>`;
}

mdsvex({
	highlight: {
		highlighter
	}
})
```

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

### Mdsvex: Disable Layouts

Source: https://mdsvex.pngwn.io/docs/index

Prevent Mdsvex from applying any layout to a specific file by setting the 'layout' field to 'false' in the frontmatter.

```yaml
---
layout: false
---
```

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

### Configure Custom Layout in Mdsvex

Source: https://mdsvex.pngwn.io/docs/index

Set a custom layout component for mdsvex files. You can provide a string path to the layout component or an object mapping names to layout paths, including a default fallback.

```javascript
import { join } from "path";

const path_to_layout = join(__dirname, "./src/Layout.svelte");

mdsvex({
	layout: path_to_layout
});
```

```javascript
mdsvex({
	layout: {
		blog: "./path/to/blog/layout.svelte",
		article: "./path/to/article/layout.svelte",
		_: "./path/to/fallback/layout.svelte"
	}
});
```

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

### Mdsvex: Define Custom Components in Layout

Source: https://mdsvex.pngwn.io/docs/index

Replace default HTML elements generated from Markdown within Mdsvex files by exporting custom Svelte components from the 'context="module"' script in your layout file. Component names must match the HTML elements they replace (e.g., 'h1', 'p').

```svelte
<script context="module">
  import { h1, p, li } from './components.js';
  export { h1, p, li };
</script>
```

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

### Mdsvex Default Extensions

Source: https://mdsvex.pngwn.io/docs/index

Shows the default value for the `extensions` option in mdsvex, which is an array containing '.svx'.

```javascript
extensions: string[] = [".svx"];
```

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

### Smartypants Ellipses Transformation

Source: https://mdsvex.pngwn.io/docs/index

Details the `ellipses` option within `smartypants`, which converts triple-dot characters into a single Unicode ellipsis character.

```javascript
ellipses: boolean = true;

// Converts triple-dot characters (with or without spaces) into a single Unicode ellipsis character.
//  * words... **becomes** words…
```
Tokens:
Raw