# @elderjs/plugin-markdown

> Easily create routes from your markdown files on your Elder.js site using the remark ecosystem.

Latest version **1.8.0-beta.7** (published 2022-07-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @elderjs/plugin-markdown
pnpm add @elderjs/plugin-markdown
yarn add @elderjs/plugin-markdown
bun add @elderjs/plugin-markdown
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.8.0-beta.7 |
| Published | 2022-07-15 |
| First published | 2020-09-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.19.0 |
| Dependencies | 14 |
| Unpacked size | 261.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 80 |
| Author | Nick Reese |
| Maintainers | nickreese, lukeed |
| Keywords | elder.js, elderjs, svelte, ssg, static, markdown, remark |

## Links

- npm: https://www.npmjs.com/package/@elderjs/plugin-markdown
- Repository: https://github.com/Elderjs/plugins
- Homepage: https://elderguide.com/tech/elderjs/
- Issues: https://github.com/Elderjs/plugins/issues
- npm.io page: https://npm.io/package/@elderjs/plugin-markdown

## Dependencies (14)

- [yaml](https://npm.io/package/yaml.md) 1.10.2
- [shiki](https://npm.io/package/shiki.md) ^0.9.6
- [rehype](https://npm.io/package/rehype.md) ^12.0.1
- [remark](https://npm.io/package/remark.md) ^14.0.2
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.1.0
- [fast-glob](https://npm.io/package/fast-glob.md) ^3.2.11
- [remark-gfm](https://npm.io/package/remark-gfm.md) ^3.0.1
- [rehype-slug](https://npm.io/package/rehype-slug.md) ^5.0.1
- [remark-html](https://npm.io/package/remark-html.md) ^15.0.1
- [remark-slug](https://npm.io/package/remark-slug.md) ^6.1.0
- [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^4.1.0
- [remark-frontmatter](https://npm.io/package/remark-frontmatter.md) ^4.0.1
- [hast-util-to-string](https://npm.io/package/hast-util-to-string.md) ^2.0.0
- [remark-extract-frontmatter](https://npm.io/package/remark-extract-frontmatter.md) ^3.2.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 1.8.0-beta.7 (latest) — 2022-07-15
- 1.8.0-beta.6 — 2022-07-15
- 1.8.0-beta.5 — 2022-07-15
- 1.8.0-beta.4 — 2022-07-14
- 1.3.10 — 2022-04-29
- 1.3.9 — 2022-04-13
- 1.3.8 — 2022-03-25
- 1.3.7 — 2022-03-07
- 1.3.6 — 2022-03-04
- 1.3.5 — 2022-03-04
- 1.3.4 — 2021-10-08
- 1.3.3 — 2021-10-08
- 1.3.2 — 2021-09-25
- 1.3.1 — 2021-09-13
- 1.3.0 — 2021-08-10
- … 49 more at https://npm.io/package/@elderjs/plugin-markdown/versions

## README

# Elder.js Plugin: Markdown

An extensible markdown parser for [Elder.js](https://github.com/Elderjs/elderjs/) powered by [remark](https://github.com/remarkjs/remark).

Use it to create a blog, or site, just configure and it'll parse your markdown and make it available in your Svelte templates.

> **IMPORTANT**: Upstream Shiki changed the name of the themes available. This means if you are upgrading to 1.3.0 from a version before you may need to update your theme name.

## Install

```bash
npm install --save @elderjs/plugin-markdown
```

## Config

Once installed, open your `elder.config.js` and configure the plugin by adding `@elderjs/plugin-markdown` to your plugin object.

```javascript
plugins: {
  '@elderjs/plugin-markdown': {
    routes: [], // if all of your markdown lives in ./src/routes/blog/, you'd add 'blog' to this array.
    slugFormatter: function(relativeFilePath, frontmatter) {
      return false; // If needed, a custom slug for the url can be crafted from the relative path to the file and
      // frontmatter in it (if any). slugFormatter must be a function and must return a string to be used.
    },
    useSyntaxHighlighting: false // This plugin ships with syntax highlighting ability for your convenience. Recommend setting true for technical blogs. See below for customizing options
  }
}
```

## Example Config

```javascript
plugins: {
  '@elderjs/plugin-markdown': {
    routes: ['articles'], // if all of your markdown lives in ./src/routes/blog/, you'd add 'blog' to this array.
    contents: {
      blog: 'src/contents/articles' // if you want to add custom path to your route relative to the root directory
    }
    slugFormatter: function(relativeFilePath, frontmatter) {
      return false; // If needed, a custom slug for the url can be crafted from the relative path to the file and
      // frontmatter in it (if any). slugFormatter must be a function and must return a string to be used.
    },
    useSyntaxHighlighting: false, // This plugin ships with syntax highlighting ability for your convenience. Recommend setting true for technical blogs. See below for customizing options
    useGitHubFriendlyMarkdown: false, // adds support for GFM (autolink literals, strikethrough, tables, tasklists).
  }
}
```

> **Caveat:** Currently, when your contents path is outside of the src directory (eg: `rootdir/articles/` ) the dev server will not be able to pickup changes on your markdown files. However it can build just fine.

## Customizing the Defaults

Below are the default settings of the plugin. You can adjust them to your needs.

```javascript
plugins: {

  '@elderjs/plugin-markdown': {
    routes: [], // a list of routes, the plugin should look for markdown in.
    contents: {}
    remarkPlugins: [
      frontmatter, // 'remark-frontmatter' package
      [extractFrontmatter, { name: 'frontmatter', yaml: yaml.parse }], // 'remark-extract-frontmatter' and 'yaml' packages.
      remarkSlug, // 'remark-slug' package
      [remarkHtml, { sanitize: false }], // 'remark-html' package
    ],
    // If you need to customize syntax highlighting, pass an options object instead of true
    // If you choose to pass your own remarkPlugins above, this feature is disabled - you can choose to copy out the code in rehype-shiki.js or roll your own syntax highlighting
    useSyntaxHighlighting: {
      theme: 'nord' // available themes: https://github.com/shikijs/shiki/blob/main/docs/themes.md - try dark-plus or github-light
      // theme is the only option available - for now.
    },
    // If you need to customize the gfm plugin, pass an object instead of true
    // Available options can be found in the remark-gfm repo: https://github.com/remarkjs/remark-gfm#options
    useGitHubFriendlyMarkdown: false, // adds support for GFM (autolink literals, strikethrough, tables, tasklists).
    useElderJsPluginImages: true, // if you are using the @elderjs/plugin-images the plugin replace all markdown images with the {{picture src="" alt="" /}} shortcode.
    useTableOfContents: false, // adds tocTree to each route's data object.
    createRoutes: true, // creates routes in allRequests based on collected md files.
  },

}
```

A note on the default syntax highlighting - we use [shiki](https://shiki.matsu.io/) (compared to other well known options) because it highlights everything in inline styles (so no extra JS/CSS needed), has extensive language support, and can use any VS Code theme including your own custom one. We have _not_ yet exposed this last feature to you as an option for this plugin - if you want this feature and are interested in implementing, please feel free to open an issue. If you wish to use your own syntax highlighting, you can add it to your `remarkPlugins` array, or set `useSyntaxHighlighting: false` and implement separately from this markdown toolchain.

## Getting all Markdown For a Route:

An object representing all of the markdown the plugin parsed from the defined `routes` is available at `data.markdown`.

If you are looking to get an array of the markdown for a specific route such as `blog` you can access it `data.markdown.blog`.

## `helpers.markdownParser`:

In addition to parsing the markdown in the given routes, this plugin makes available the configured [remark](https://github.com/remarkjs/remark) parser at `helpers.markdownParser` during the `bootstrap` hook.

This means you can use the same markdown parser to parse markdown from other sources if needed.

For full documentation please review [remark's docs](https://github.com/remarkjs/remark). That said, the default plugin config can be used to parse markdown like so:

- `helpers.markdownParser.processSync(mdText)` if you are not using syntax highlighting.
- `helpers.markdownParser.process(mdText)` if you are using syntax highlighting. **Note that because this is an async function, it will not run inside of a non-hydrated Svelte file. To get around this, you'll want to execute the function in the `data` portion of your `route.js` file.**

## Remark Plugins:

If you need to customize the remark plugins that are used here are some notes:

1. The `remarkPlugins` array are added to `remark` in the order they are given.
1. If you add a single plugin in your `elder.config.js`, you must specify a full `remark` pipeline.
1. If a plugin such as `remark-extract-frontmatter` needs an array of options, you can pass in an array like so: `remarkPlugins: [[extractFrontmatter, { name: 'frontmatter', yaml: yaml.parse }]]`

The default remarkPlugins are exported for ease of use via the package. `const { remarkPlugins } = require('@elderjs/plugin-markdown');`

### Notes:

- By default, if there is a `date` field in your frontmatter it will sort all of the markdown for that route by it.
- If there is a `slug` field in your frontmatter it will use that for the slug, if not it falls back to the filename.
- If `draft: true` is in a file's frontmatter or a slug is prefixed with `draft-` these markdown files will be hidden when `process.env.NODE_ENV === 'production'`. They will also be prefixed with `DRAFT: [Post Title Here]` to make this functionality more obvious.

---
_Source: https://npm.io/package/@elderjs/plugin-markdown · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._