k-community/markdown-field

为 Kirby 4 的超高级 markdown 编辑器

维护者

详细信息

github.com/fabianmichael/kirby-markdown-field

主页

源代码

问题

资助包维护！
fabianmichael

安装次数: 24,001

依赖关系: 0

建议者: 0

安全性: 0

星标: 160

关注者: 10

分支: 14

开放性问题: 12

语言:JavaScript

类型:kirby-plugin

3.0.0-alpha.2 2023-11-30 09:05 UTC

Requires

Requires (Dev)

MIT 800fe5241abf85bd7309e982cdf0d4deea0b79ec

  • Sylvain Julé <contact.woop@sylvain-jule.fr>
  • Fabian Michael <hallo.woop@fabianmichael.de>

This package is auto-updated.

Last update: 2024-09-19 13:49:47 UTC

README

增强型、可扩展的 Kirby CMS Markdown 字段。现在可用版本 2！

功能

  • Markdown 和 Kirbytext 的精致、微妙高亮
  • 基于上下文的格式切换（几乎类似 WYSIWYG）
  • 智能缩进，用于包裹标题、列表项和引用块
  • 大多数操作都有键盘快捷键
  • 自定义工具栏按钮
  • 自定义语法高亮
  • 可选显示空格字符
  • 可点击的 URL
  • 可配置的 Markdown 语法（例如，从 _italic_ 或 *italic* 中选择）
  • 用支持语法高亮的版本替换了 Kirby 的默认 Markdown 块
  • 支持基于触摸的设备，性能优异（归功于 CodeMirror 6）

💡 TL;DR: 你们一直等待的 Markdown 字段！

Screenshot of the editor field

概述

此插件完全免费，并按照 MIT 许可证发布。但是，如果您在使用它进行商业项目并希望帮助我保持维护，请考虑 ❤️ 赞助我 以确保插件持续发展。

目录

1. 安装

此插件版本需要 PHP 8.1 和 Kirby 4.0.0 或更高版本。推荐的安装方法是使用 Composer

$ composer require fabianmichael/kirby-markdown-field

或者，下载并将此存储库复制到 /site/plugins/markdown-field

2. 设置

此字段可以替换您设置的任何 textarea 字段，并且无需配置即可直接使用

editor:
  label: My markdown editor
  type: markdown

3. 选项

3.1. 可用选项

您可以使用与 textarea 字段 相同的选项，并且还有一些额外的选项

3.2. 字体设置

您可以选择等宽字体（monospace）和无衬线字体（sans）。等宽字体提供了更复杂的布局，带有多行列表元素、标题和引用块的缩进——这些都是对于比例字体来说更难实现（并且计算速度更慢）的事情。

虽然无衬线字体可能一开始对非技术性作者更有吸引力，但在大多数情况下，等宽字体应该是首选版本。

3.3. 按钮

此字段包含了通常的 textarea 按钮，以及许多额外的按钮。

headlines 可以包含从 h1 到 h6 的所有标题，因此接受一个允许的级别数组（默认是 h1, h2, h3）。在这种情况下，使用 headlines 作为键

buttons:
  headlines: # no dash before the key name
    - h1
    - h2
    - h3
    - h4
    - h5
    - h6

您还可以访问额外的按钮

buttons:
  - blockquote
  - hr
  - strikethrough
  - pagelink
  - footnote

如果您不需要它，您可以隐藏工具栏。这将禁用所有格式的键盘快捷键。

buttons: false

可用的按钮完整列表。如您所见，一些按钮还可以有配置选项。以加粗按钮为例。Markdown允许使用不同的语法来表示加粗文本，即__加粗__和**加粗**。编辑器的语法高亮器将始终识别这两种语法，但您可以通过点击工具栏按钮或按相应的快捷键来调整编辑器将使用的语法。

对于链接和页面链接按钮，您可以指定是否插入markdown或kirbytext标记。默认情况下，这将由kirbytext选项确定，但可以按按钮分别覆盖。

所有按钮配置都是可选的，如果您想坚持默认设置，可以使用- ul代替ul: -。

buttons:
  headlines:
    - h1
    - h2
    - h3
    - h4
    - h5
    - h6
  bold: ** # or `__`
  link: null # or `markdown` or `kirbytext`
  pagelink: null # or `markdown` or `kirbytext`
  italic: * # or `_`
  - strikethrough
  - code
  ul: - # or `*`/`+`
  - ol
  link:
    blank: true # Show option for opening link in a new tab.
  - blockquote
  hr: *** # or `---`/`___`
  - strikethrough
  - highlight # textmarker (not supported by Kirby’s default markdown parser.)
  - pagelink
  - file
  - footnote
  - invisibles
  - divider # can be used multiple times

3.4. 键盘快捷键

ℹ️键盘快捷键仅适用于工具栏中启用的按钮/标题级别。

块格式

内联格式

其他

URLs

  • 当您选择一些文本并粘贴URL时，它将自动创建一个链接标签，并使用当前选定的文本作为链接文本。

3.5. 页面

您可以通过设置pages选项并使用查询来限制Pagelink对话框中显示的选项（如果未设置，您将能够浏览整个网站树）。

pages: kirby.page('my-page').children

您还可以将pages选项设置为具有来自页面字段的其他属性的对象，例如信息和文本。

pages:
  query: kirby.page('my-page').children
  info: "{{ page.tags }}"
  text: "{{ page.title.upper }}"

3.6. 大小

您可以在字段为空时定义字段的高度。默认为两行，这与textarea的默认空高度相似。

如果您想使字段模仿文本字段，但顶部有一些markdown高亮显示，请将大小设置为一行并设置buttons: false。

所有预定义的大小有

- one-line
- two-lines
- small (same as textarea)
- medium (same as textarea)
- large (same as textarea)
- huge (same as textarea)

请注意，您可以使用一些自定义面板CSS将默认高度设置为任何高度。首先，将size选项设置为任何您想要的字符串

size: custom-size

然后在您的panel.css

.k-markdown-input-wrap[data-size="custom-size"] {
  --cm-min-lines: 20;
}

4. 扩展 API

API已从版本1更改，旧的插件不再兼容，需要一些调整。请参阅extension-examples文件夹。

有两种类型的扩展，允许您扩展编辑器以更好地满足您的特定需求

  • 自定义按钮：您可以定义自己的按钮，这些按钮可以添加到编辑器工具栏中。按钮可以定义键盘快捷键，显示下拉菜单，甚至显示弹出窗口。
  • 自定义扩展：您可以定义自己的编辑器扩展。一个例子可以在extension-examples/indent-with-tab文件夹中找到。
  • 自定义高亮：您可以定义基于正则表达式的自定义高亮，允许您突出显示任何文本，例如自定义语法的标记（例如全局文本片段或Wiki风格的链接）

4.1 页面、文件和上传的自定义选项

您的扩展可以使用特殊端点来扩展页面的基本选项、文件和上传，这些参数在按钮配置中设置。请参阅extension-examples/custom-pagelink文件夹中的示例。

// special routes to read options from the button configuration
this.input.endpoints.field + "/myextension/pages"
this.input.endpoints.field + "/myextension/uploads"
this.input.endpoints.field + "/myextension/files"

最终用户可以配置扩展的选项作为按钮配置的一部分。

text:
  type: markdown
  files:
    […]
  pages:
    […]
  buttons:
    myextension:
      pages:
        query: site.index
        info: "{{ page.tags }}"

5. 开发

  • 克隆仓库
  • cd到您新创建的文件夹（命名为kirby-markdown-field，或您选择的任何名称）
  • npm install以获取所有依赖项
  • 然后
# Dev mode
npm run dev

# Build plugin + autoprefix styles
npm run build

您必须在推送仓库之前运行构建过程，否则热重载代码将防止它在任何安装中工作。

7. 从版本 1 迁移

  • 现在设置可用的标题级别的方式略有不同，请参阅3.3. 按钮。这是必要的，以便未来/扩展中允许多个可配置的下拉菜单。
  • 水平线按钮已被重命名为 hr。
  • 已移除 modals 选项。点击链接按钮将始终显示模态框。
  • 已将 link 和 email 按钮合并为一个弹出窗口。
  • 已将 blank 选项从全局选项移至链接按钮。
  • 已将 不可见 选项替换为名为 invisibles 的按钮。只需将其添加到您的工具栏设置中即可。
  • 注册自定义按钮的 API 已更改。请参阅 extension-examples 文件夹中的示例。
  • 已移除字体缩放选项。Markdown 字段版本 2 只接受 monospace 和 sans 作为字体选项。如果您需要标题的缩放，请考虑使用 Kirby 的 Blocks 字段。
  • 已移除全局字段选项。请使用字段预设代替。（请参阅 https://getkirby.com/docs/guide/blueprints/extending-blueprints#reusing-and-extending-single-fields）。
  • 已移除 direction 选项。CodeMirror 6 会自动确定面板当前文本的方向。

8. 已知问题

  • Kirbytags: 在嵌套括号或嵌套 Kirbytags 的一些边缘情况下，高亮显示可能不同于 Kirby 解析标记的方式。这不应该成为大多数日常用例的问题。您也不能在 Kirbytags 中有多个连续的换行符，否则高亮器会失败。这是由于 Markdown 在块和内联元素之间创建清晰分隔的方式所致。
  • HTML 块中的 Kirbytags 不会高亮显示，因为 CodeMirror 使用它自己的 HTML 解析器进行处理，这会在这些区域中禁用所有 Markdown 高亮显示。Parsedown Extra 支持在 HTML 块级元素上使用 markdown="1" 属性，而 CodeMirror 的 Markdown 解析器不支持此属性。
  • 内联格式切换：当处理非常复杂的重新格式化时，选择有时会以意想不到的方式表现。解决这个问题需要在整个转换过程中进行更复杂的选择/光标跟踪。在我看来，它仍然比大多数其他 Markdown 编辑器表现更好，并且不会导致数据丢失，所以 ¯\_(ツ)_/¯。

9. 不支持的内容（以及永远不会支持的内容）

自 Markdown 问世以来，其使用方式已发生变化，特别是在 GFM ("GitHub-Flavored Markdown") 变得流行并添加了一些元素之后。

  • Setext 样式的标题：如果您不知道这些是什么，就别管它们了。它们有基本的高亮显示，但既不会被工具栏识别为标题，也不会在更改格式时受到尊重。请使用 ATX 样式的标题代替（例如 ## 标题级别 2）。
  • 缩进的代码块：请使用带围栏的代码块。

10. 许可证

MIT（但您强烈鼓励您 ❤️ 赞助我，如果这款软件帮助您付账的话）。

11. 致谢

文本编辑器

贡献者

@fabianmichael, @sylvainjule, @medienbaecker, @mtsknn, @nsteiner, @rasteiner, @thomasfahrland, @johannschopplich

灵感来源于