fabianmichael/kirby-markdown-field

为 Kirby 4 提供的超级复杂的 Markdown 编辑器

维护者

详细信息

github.com/fabianmichael/kirby-markdown-field

主页

源代码

问题

资助包维护！
fabianmichael

安装次数: 5 195

依赖关系: 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:41:20 UTC

README

增强型、可扩展的 Kirby CMS Markdown 字段。现在提供第 2 版！

功能

  • Markdown 和 Kirbytext 的精致但微妙的突出显示
  • 基于上下文的格式切换（几乎类似于 WYSIWYG）
  • 智能缩进以包裹标题、列表项和引用块
  • 大多数操作都有键盘快捷键
  • 自定义工具栏按钮
  • 自定义语法突出显示
  • 选项显示空白字符
  • 可点击的 URL
  • 可配置的 Markdown 语法（例如，从 _italic_ 或 *italic* 选择）
  • 用支持语法高亮的 Markdown 替换 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

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

对于 link 和 pagelink 按钮，您可以选择是否插入 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. 键盘快捷键

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

块格式

内联格式

其他

URL

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

3.5. 页面

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

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

您还可以将 pages 选项设置为一个具有来自 pages 字段 的其他属性的对象，例如 info 和 text。

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

3.6. 大小

您可以在字段为空时定义字段的高度。默认为 two-lines，这模仿了 textarea 的默认空高度。

如果您想使字段模仿文本字段，但在顶部有一些 markdown 高亮显示，请将大小设置为 one-line 并将 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. 按钮。这是为了允许在未来/扩展中拥有多个可配置的下拉菜单。
  • 将 horizontal-rule 按钮重命名为 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

灵感来源于