# @avo-hq/marksmith 中文文档

规范地址：https://npmcn.com/package/%40avo-hq/marksmith/

版本：0\.5\.1
npm 元数据更新时间：2026-04-24T06:38:33.086Z
中文译文更新时间：2026-11-07T08:15:34.665Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40avo-hq/marksmith
原文对照：https://npmcn.com/package/%40avo-hq/marksmith/?lang=original
项目主页：https://github.com/avo-hq/marksmith
源码仓库：https://github.com/avo-hq/marksmith

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：147 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2025-01-21T18:53:20.507Z
- 最新版本发布：2026-04-24T06:38:32.940Z
- 近 30 天下载量：13879（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 2 个）

## 中文简介

Ruby 和 Rails 的 GitHub 式标记下调编辑器

## 安装

```sh
npm install @avo-hq/marksmith
```

也可以使用：`pnpm add @avo-hq/marksmith`、`yarn add @avo-hq/marksmith`、`bun add @avo-hq/marksmith`

## README

# 马克史密斯

[![CI](https://github.com/avo-hq/marksmith/actions/workflows/ci.yml/badge.svg)](https://github.com/avo-hq/marksmith/actions/workflows/ci.yml)

Marksmith是 Rails apps 的 GitHub 风格的标记下调编辑器.

它支持活性存储附件并带有内置的标记下预览渲染器.

![Marksmith logo](https://npmcn.com/package/%40avo-hq/marksmith/marksmith.png)

![Marksmith demo](https://npmcn.com/package/%40avo-hq/marksmith/marksmith.gif)

> \[尖叫声\] Marksmith正处于开发的初始阶段. 已接近β放出,但API可能会改变并被预期出出出bug. 请继续使用此库, 并在 GitHub Repo 中报告任何问题 .

临时现场演示, 在描述字段下: [https://main.avodemo.com/avo/resources/projects/new (中文(简体) )](https://main.avodemo.com/avo/resources/projects/new)

## 使用量

```erb
<%= marksmith_tag :body %>
```

## 安装

#### 先决条件

Marksmith与 Rails 应用集成,使用刺激控制器和涡轮流,所以必须已经安装并配置以下设备:

-   [`@hotwired/stimulus` 软件包](https://github.com/hotwired/stimulus)
-   [`@hotwired/turbo` 软件包](https://github.com/hotwired/turbo)
-   [`turbo-rails` 宝石](https://github.com/hotwired/turbo-rails)

#### 1\. 添加 `marksmith` 给您的 `Gemfile`

让 Bundler 通过运行此命令来添加 :

```bash
bundle add marksmith commonmarker
```

或手动安装.

将此行添加到您的应用程序的 Gemfile 中 :

```ruby
# Gemfile
gem "marksmith"
# Add a markdown parser
gem "commonmarker"
```

#### 2\. 安装国家防范机制软件包,以导入刺激JS控制器.

从 npmjs.org 安装软件包 .

```bash
$ yarn add @avo-hq/marksmith
```

或者用导入图把它钉上.

```bash
bin/importmap pin @avo-hq/marksmith
```

在您的应用程序中导入并注册控制器 。 这个 `ListContinuationController` 这是可选的,并且只有在您想要在减记中继续列表时才需要.

```js
import { MarksmithController, ListContinuationController } from '@avo-hq/marksmith'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

> \[注\] Marksmith默认与少数依赖关系相捆绑. 如果您想要手动导入这些依赖性, 只从包中导入控制器使用 `/controller` 路径.

```js
// Manually import Marksmith's dependencies
import '@github/markdown-toolbar-element'
import { DirectUpload } from '@rails/activestorage'
import { post } from '@rails/request.js'
import { subscribe } from '@github/paste-markdown'

// Import just the controller
import { MarksmithController } from '@avo-hq/marksmith/core'

application.register('marksmith', MarksmithController)
```

#### 3\. 将样式标签添加到您的 `application.html` 版式

```erb
<%= stylesheet_link_tag "marksmith" %>
```

#### 4\. 使用该工具

使用窗体帮助标记或附加在窗体构建器上.

```erb
<%= marksmith_tag :body, value: "### This is important" %>
or
<%= form.marksmith :body %>
```

数值以纯文本 QQ 存储于数据库

## 配置

Marksmith接受一些配置选项.

### 外地选项

字段支持一些常规选项,如 `disabled`, (中文(简体) ), `placeholder`, (中文(简体) ), `autofocus`, (中文(简体) ), `style`, (中文(简体) ), `class`, (中文(简体) ), `data`,以及 `value`但也是一种习俗.

`extra_preview_params` - 向预览渲染器发送额外的参数.

`enable_file_uploads` - 是否启用文件上传 .

`upload_url` 用于文件上传的 URL 。 如果不提供,编辑器将使用 `rails_direct_uploads_url` 帮手.

```erb
<%= marksmith_tag :body,
  disabled: true,
  placeholder: "Write your best markdown here.",
  extra_preview_params: { foo: "bar" },
  enable_file_uploads: true,
  upload_url: nil
  %>
```

### 弹出配置文件

Marksmith 带有一个默认配置文件, 您可以弹出到您的应用程序 .

```bash
bin/rails generate marksmith:install
```

这将创建一个 `config/initializers/marksmith.rb` 文档在您的应用程序中.

### 挂载路径

引擎默认安装于 `/marksmith`设置时可以更改它 `Marksmith.configuration.mount_path` 走向另一条路.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.mount_path = "/markdown"
end
```

### 上载引擎

引擎是默认挂载的, 但你可以通过设置来禁用它 `Marksmith.configuration.automatically_mount_engine` 改为 `false` 然后手动挂载引擎 `routes.rb` 文档.

```ruby
# config/routes.rb
Rails.application.routes.draw do
  mount Marksmith::Engine => Marksmith.configuration.mount_path
end
```

## 内置预览渲染器

制造器由 [`Commonmarker`](https://github.com/gjtorikian/commonmarker) 默认但可更改为 [`Redcarpet`](https://github.com/vmg/redcarpet) 或者说 [击倒了](https://github.com/gettalong/kramdown) 或通过自定义 `Marksmith::Renderer` 型号. 它支持标题等基本样式, `strong`, (中文(简体) ), `italic` 还有其他.

在你身边 `show.html.erb` 视图或要制作编译标记的地方使用 `marksmithed` 帮助器和它会通过渲染器运行内容.

```erb
<%== marksmithed post.body %>
```

> \[尖叫声\] 使用 `<%==` 标记会输出原始的 HTML, 因此确保您对内容进行消毒以避免 XSS 攻击 .
> 
> 看我们怎么做 [这里](https://npmcn.com/package/%40avo-hq/marksmith/app/views/marksmith/shared/_rendered_body.html.erb#L2)。 。 。 .
> 
> ```ruby
> # sample sanitization
> sanitize(body, tags: %w(table th tr td span) + ActionView::Helpers::SanitizeHelper.sanitizer_vendor.safe_list_sanitizer.allowed_tags.to_a)
> ```

## 自定义渲染器

Marksmith带了一个默认的渲染器 `commonmarker` 默认但可更改为 `redcarpet` 或者说 `kramdown` 在配置中.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.parser = "redcarpet"
end
```

如果你在用的话 `redcarpet`,您可以通过配置覆盖默认的解析器旗帜。 默认符合内置行为.

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.parser = "redcarpet"
  config.redcarpet_options = {
    underline: false,
    highlight: false
  }
end
```

或直接覆盖单个旗帜:

```ruby
# config/initializers/marksmith.rb
Marksmith.configure do |config|
  config.parser = "redcarpet"
  config.redcarpet_options.underline = false
  config.redcarpet_options.highlight = false
end
```

### 添加自己的渲染器

你可以完全定制 制造器通过压倒 `Marksmith::Renderer` 型号.

```ruby
# app/models/marksmith/renderer.rb
module Marksmith
  class Renderer
    def initialize(body:)
      @body = body
    end

    def render
      # Your custom renderer logic here
    end
  end
end
```

## 活动存储

编辑器支持 [活动集成](https://guides.rubyonrails.org/active_storage_overview.html) 使用拖放和粘贴文件上传到字段.

在Avo中使用的Whe支持使用 [媒体资料库](http://docs.avohq.io/3.0/media-library.html)。 。 。 .

## 继续列表

Marksmith有一个伟大的选入功能 你可以继续你的列表. 我们需要添加 `ListContinuation` 控制器也一样.

```js
import { ListContinuationController, MarksmithController } from '@avo-hq/marksmith'
// or /core for the no-dependencies version
import { ListContinuationController, MarksmithController } from '@avo-hq/marksmith/core'

application.register('marksmith', MarksmithController)
application.register('list-continuation', ListContinuationController)
```

## 黑暗模式

Marksmith在使用时带有暗模式 `.dark` 课上的包装元素策略.

```erb
<!-- Wrapper element -->
<div class="dark">
  <%= marksmith_tag :body %>
</div>

<!-- or -->
<%= form_with model: post, class: "dark" do |form| %>
  <%= form.marksmith :body %>
<% end %>

<!-- or -->
<html class="dark">
  <%= marksmith_tag :body %>
</html>
```

## 谁用马克史密斯?

-   [阿沃语Name](https://avohq.io/) - Ruby on Rails Code-Based App Builder框架

_打开 PR 并在此添加您的工程_

## 捐款

贡献方向在这里.

## 许可证

该宝石作为公开源码,按照以下规定提供: [MIT 许可证](https://opensource.org/licenses/MIT)。 。 。 .

## 在阿沃的使用

Marksmith在默认的 Avo 中出色工作 [标记下字段](https://docs.avohq.io/3.0/fields/markdown.html)。 。 。 .

## 其他开源工作

-   [`active_storage-blurhash`](https://github.com/avo-hq/active_storage-blurhash) - 插头n游戏 [模糊](https://blurha.sh/) 存储在 ActiveStorage 中的图像集成
-   [`avo`](https://github.com/avo-hq/avo) - 在铁路上用Ruby建造内部工具
-   [`class_variants`](https://github.com/avo-hq/class_variants) - 简便地配置样式,并将其应用为类。 当你执行Tailwind CSS组件 并用不同的状态调用它们时 非常有用.
-   [`prop_initializer`](https://github.com/avo-hq/prop_initializer) - 在Ruby类上定义属性的灵活工具.
-   [`stimulus-confetti`](https://github.com/avo-hq/stimulus-confetti) - 在你的"刺激"JS应用程序中加入孔雀最简单的方法

## 试试阿沃

如果你喜欢这颗宝石的话 [阿沃语Name](https://github.com/avo-hq/avo)。它将您的工程速度翻倍,而不雇用额外的开发者。 团队在使用Avo的"铁路上路比"(Ruby on Rails)上更快地搭建了"内部工具","管理面板","内容管理系统","CRM"等各类业务Apps 10x.

## 解决问题

如果你从Vite那里得到431个错误, 清除你的Brower的缓存 `localhost` (chrome://settings/content/all?search Subpage=localhost). 互联网档案馆的存檔,存档日期2013-12-21.

## 释放

运行 `bin/release x.y.z`,使用时 `--dry` 以跳过出版。 这不是一能之道。 如果放出失败, 请注意进程所剩位置并手动继续 .

### 细节

在开发中,我们使用 `vite-rails` 汇编并重新装入 JS & CSS 更改.

释放时我们使用 `rollup` 来编译 StimulusJS 控制器和 `@tailwindcss/cli` 汇编 CSS.

JS代码被推到npmjs.org上 `@avo-hq/marksmith` cSS文件在宝石中运出.

## 常见问题

### @avo-hq/marksmith 是什么？

Ruby 和 Rails 的 GitHub 式标记下调编辑器

### 如何安装 @avo-hq/marksmith？

在项目目录运行 npm install @avo-hq/marksmith，或使用 pnpm add / yarn add / bun add。

### @avo-hq/marksmith 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/avo-hq\_\_marksmith 是否存在。

### @avo-hq/marksmith 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @avo-hq/marksmith 可以商用吗？

@avo-hq/marksmith 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @avo-hq/marksmith 的下载量有多少？

根据 npm 官方下载统计，@avo-hq/marksmith 在 2026/10/07 – 2026/11/05 这 30 天内被下载 13,879 次，日均约 463 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @avo-hq/marksmith 还在维护吗？

最新版本 0\.5\.1 发布于 2026/04/24（6 个月前）；至今共发布 30 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/01/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。