Python-Markdown 的 KBD 扩展

这个Python-Markdown<kbd>扩展为 HTML标签添加了 markdown 语法。该<kbd>标签通常用于指示用户输入。此扩展为最多三个不同样式的<kbd>标签提供降价语法。例如，使用 UI 指南的作者可能希望设置<kbd>标签样式以指示用户通过键盘键、按钮和菜单选项进行的输入。KBD 扩展使作者可以为每种类型的用户输入创建特定的 css，并使用 markdown 语法来相应地设置其指南的样式。

有关详细信息，请参阅用法。

安装

pip install kbdextension

用法

KBD 扩展是一个内联处理器，用于为内联<kbd>标签添加降价语法。用双括号、双括号或双括号括起来的文本将用 HTML<kbd>标记括起来。KBD 扩展旨在与 Python-Markdown 默认扩展一起使用。如果在与其他 3rd 方扩展配对时遇到冲突，可以单独启用或禁用 KBD 扩展降价指示器。括号默认启用（但可以禁用）。大括号和括号默认禁用（但可以单独启用）。默认情况下，页面的默认 css 实现将应用于<kbd>标签。可以将 KBD 扩展配置为对每个 KBD 降价指示器使用自定义 css。

括号降价

markdown.markdown("Press the [[Enter]] key!", extensions=[KbdExtension()])

默认情况下启用括号语法。这将产生以下 HTML：

<p>Press the <kbd>Enter</kbd> key!</p>

自定义 css 类可以应用于<kbd>括号降价产生的标签。

markdown.markdown(
    "Press the [[Enter]] key!", 
    extensions=[KbdExtension(brackets_css="bracket_css")]
)

这将产生以下 HTML：

<p>Press the <kbd class="bracket_css">Enter</kbd> key!</p>

大括号降价

默认情况下，大括号降价是禁用的。它可以通过在构造函数中设置enable_braces为来启用。True

markdown.markdown(
    "Click the {{Search}} button!", 
    extensions=[KbdExtension(enable_braces=True)]
)

这将产生以下 HTML：

<p>Click the <kbd>Search</kbd> button!</p>

与括号语法一样，自定义 css 类可以应用于<kbd>大括号 markdown 生成的标签。

markdown.markdown(
    "Click the {{Search}} button!",
    extensions=[KbdExtension(enable_braces=True, braces_css="braces-css")],
)

这将产生以下 HTML：

<p>Click the <kbd class="braces-css">Search</kbd> button!</p>

括号降价

默认情况下禁用括号降价。它可以通过在构造函数中设置enable_parens为来启用。True

markdown.markdown(
    "Click the ((File)) menu!", 
    extensions=[KbdExtension(enable_parens=True)]
)

这将产生以下 HTML：

<p>Click the <kbd>File</kbd> menu!</p>

与括号语法一样，自定义 css 类可以应用于<kbd>括号降价产生的标签。

markdown.markdown(
    "Click the ((File)) menu!",
    extensions=[KbdExtension(enable_parens=True, parens_css="parens-css")],
)

这将产生以下 HTML：

<p>Click the <kbd class="parens-css">File</kbd> menu!</p>

MkDocs 配置

可以将 KBD 扩展配置为与MkDocs一起使用。该扩展提供了它自己的配置选项，如上面的使用说明中所述。配置选项嵌套在配置文件markdown_extensions:部分的键/值映射中。mkdocs.yml下面提供了此扩展的示例配置。有关在 MkDocs 中配置 markdown 扩展的更多信息，请参阅MkDocs 配置文档。

默认配置

默认配置仅启用括号语法。

markdown_extensions:
    - kbdextension

部分配置

这个部分配置示例禁用了括号降价指示符，并为<kbd>它呈现的标签启用了带有自定义 css 类的大括号降价指示符。

extra_css:
    - css/extra.css
markdown_extensions:
    - kbdextension:
        enable_brackets: false
        enable_braces: true
        braces_css: braces_kbd_css

完整配置

完整的配置启用括号、大括号和括号降价指示符以及每个自定义 css。请注意，默认情况下启用括号，因此无需将enable_brackets配置设置为true.

extra_css:
    - css/extra.css
markdown_extensions:
    - kbdextension:
        brackets_css: brackets_kbd_css
        enable_braces: true
        braces_css: braces_kbd_css
        enable_parens: true
        parens_css: parens_kbd_css

有关在 MkDocs 中配置自定义 css 的更多信息，请参阅MkDocs 配置文档。

MkDocs 示例

以下示例演示了如何使用 KBD 扩展提供的所有三个降价指示符。

首先，我们为该站点创建了自定义 CSS。对于此示例，该extra.css文件定义了我们将需要的三个自定义 KBD css 类中的每一个。该extra.css文件保存在cssMkDocsdocs_dir目录的子目录中。此示例使用了以下 css：

kbd.button-css {
    font-family: Menlo, Consolas, monospace;
    font-size: 75%;
    padding: 2px 6px;
    color: #ffffff;
    background-color: #6699cc;
    border-radius: 3px;
    -webkit-box-shadow: inset 0 0 0 1px #333333;
            box-shadow: inset 0 0 0 1px #333333;
}
kbd.menu-css {
    font-family: Menlo, Consolas, monospace;
    font-size: 75%;
    padding: 2px 4px;
    color: #333333;
    background-color: #f2f2f2;
    border-radius: 3px;
    -webkit-box-shadow: inset 0 0 0 1px #333333;
            box-shadow: inset 0 0 0 1px #333333;
} 
kbd.keyboard-css {
    font-family: Menlo, Consolas, monospace;
    font-size: 75%;
    padding: 2px 6px;
    color: #ffffff;
    background-color: #333333;
    border-radius: 3px;
    -webkit-box-shadow: inset 0 -1px 0 rgba(0, 0, 0, 0.25);
            box-shadow: inset 0 -1px 0 rgba(0, 0, 0, 0.25);
} 

接下来，我们为示例创建降价。在此示例中，我们使用所有三个 KBD 语法指示符来呈现三个不同的<kbd>HTML 标记。降价显示在这里：

Click the {{Open...}} menu or press ((CTRL)) + ((O)) to open.
Click the [[SAVE]] button to save changes.

接下来，mkdocs.yml更新配置文件以包含extra_css:完整的 KBD 扩展配置，如下所示：

extra_css:
    - css/extra.css
markdown_extensions:
    - kbdextension:
        brackets_css: button-css
        enable_braces: true
        braces_css: menu-css
        enable_parens: true
        parens_css: keyboard-css   

KBD 扩展与 MkDocs 和 Python-Markdown 一起呈现以下 HTML：

Click the <kbd class="menu-css">Open...</kbd> menu or press <kbd class="keyboard-css">CTRL</kbd> + <kbd class="keyboard-css">O</kbd> to open.
Click the <kbd class="button-css">SAVE</kbd> button to save changes.

执照

该软件是根据 MIT 许可证提供的。有关详细信息，请参阅许可证。