plugin-local

A plugin that can act as both input and output. For example, reading local markdown and generating websites or epubs, or downloading content from the website to local.

input

tasks:
  - name: test
    input:
      name: '@mark-magic/plugin-local'
      config:
        path: './book/'

path(input)

Recursively scan all markdown files and their referenced resource files under this path.

.
├─ books
│  ├─ 01.md
│  ├─ 02.md
│  └─ readme.md
└─ package.json

For example, the above directory will be scanned, regardless of how deep the hierarchy is.

books/01.md
books/02.md
books/readme.md

ignore(input)

The ignored files, support glob syntax.

output

tasks:
  - name: test
    output:
      name: '@mark-magic/plugin-local'
      config:
        path: './book/en-US/'

path(output)

The root directory for the output markdown file, required item.

Use as a library

Very useful for scenarios that need to output as local markdown files, such as output during hexo/hugo/vitepress/jekyll, no need to write plugins from scratch, but it's simpler to configure based on the output of the local plugin. The plugin @mark-magic/plugin-hexo is implemented in this way, and it even only used 30+ lines of code.

import { OutputPlugin } from '@mark-magic/core'
import path from 'path'
import * as local from '@mark-magic/plugin-local'

export interface Tag {
  id: string
  title: string
}

export function output(options?: { path?: string; base?: string }): OutputPlugin {
  const root = options?.path ?? path.resolve()
  const postsPath = path.resolve(root, 'source/_posts')
  const resourcePath = path.resolve(root, 'source/resources')
  const p = local.output({
    path: postsPath,
    meta: (it) => ({
      layout: 'post',
      title: it.name,
      abbrlink: it.id,
      tags: it.extra?.tags.map((it: { title: string }) => it.title),
      categories: it.path,
      date: it.created,
      updated: it.updated,
    }),
    contentLink: (it) => path.join('/', options?.base ?? '/', `/p/${it.linkContentId}`),
    resourceLink: (it) => `/resources/${it.resource.id}${path.extname(it.resource.name)}`,
    contentPath: (it) => path.resolve(postsPath, it.id + '.md'),
    resourcePath: (it) => path.resolve(resourcePath, it.id + path.extname(it.name)),
  })
  p.name = 'hexo'
  return p
}

Complete type definition

export interface OutputOptions {
  path: string
  meta(content: Content): any
  contentPath(content: Content): string
  resourcePath(content: Resource): string
  contentLink(o: {
    content: Content
    contentPath: string
    linkContentPath: string
    linkContentId: string
  }): string | undefined
  resourceLink(o: { resource: Resource; contentPath: string; resourcePath: string }): string | undefined
}

You can control all aspects of output when creating output plugin instances with local.output.

meta

Controls the yaml metadata at the top of markdown, by default, no metadata will be added.

# Getting Started

## Overview

Returns null and does not keep any metadata.

# Getting Started

## Overview

contentPath

Controls the actual output path of the content, by default, it is calculated based on path and the content's own path.

For example, the path is ~/code/blog/posts/, a content data is as follows:

{
  "id": "test",
  "name": "test",
  "path": ["dev", "web", "test.md"]
}

Then, the default output path is ~/code/blog/posts/dev/web/test.md.

resourcePath

Controls the actual output path of the resource, by default, it is calculated based on path and the resource's own name.

For example, the path is ~/code/blog/, a resource data is as follows:

{
  "id": "test",
  "name": "test.png"
}

Then, the default output path is ~/code/blog/resources/test.png.

contentLink

If there is a reference relationship between the content, control how to reference in the markdown file after output, the default is the relative path of the output markdown file.

For example, the content /dev/web/vscode-plugin refers to the content /dev/tool/vscode

[vscode](../tool/vscode.md)

resourceLink

If the content references a resource, control how to reference in the markdown file after output, the default is the relative path of the output resource file.

For example, the output markdown file is /posts/dev/web/vscode-plugin.md referring to the resource /resources/vscode.png

![vscode](../../../resources/vscode.png)