gdtest-keys-shortcode

A synthetic test package that exercises the Quarto shortcode for rendering keyboard keys with styled key-caps. Covers single keys, shortcut combos, platform-aware rendering, and keys in various content contexts.

Keyboard keys shortcode showcase exercising the shortcode in four user-guide pages: single keys (Esc, Enter, Tab, modifiers, arrows), shortcut combos (Ctrl+Shift+P auto-split), platform-aware rendering (macOS symbols ⌘⌥⇧⌃ vs Windows labels), and keys in context (headings, callouts, lists, blockquotes, prose).

Source files

📁 gdtest_keys_shortcode/

📄 __init__.py

"""Keyboard shortcode demo package."""

__version__ = "1.0.0"
__all__ = ["render", "transform"]


def render(template: str) -> str:
    """Render a template string.

    Parameters
    ----------
    template
        The template to render.

    Returns
    -------
    str
        Rendered output.
    """
    return template


def transform(data: list) -> list:
    """Transform a data list.

    Parameters
    ----------
    data
        Input data.

    Returns
    -------
    list
        Transformed data.
    """
    return data

📁 user_guide/

📄 01-single-keys.qmd

---
title: Single Keys
---

The `{{< keys >}}` shortcode renders individual keyboard keys
with styled key-cap appearance.

## Basic Keys

Press {{< keys "Esc" >}} to cancel.

Press {{< keys "Enter" >}} to confirm.

Press {{< keys "Tab" >}} to move to the next field.

Press {{< keys "Space" >}} to toggle.

## Modifier Keys

The {{< keys "Ctrl" >}} key is used for shortcuts.

Hold {{< keys "Shift" >}} to select a range.

The {{< keys "Alt" >}} key triggers alternate actions.

## Letter and Number Keys

Press {{< keys "A" >}} to select all (with Ctrl).

Press {{< keys "F5" >}} to refresh.

Press {{< keys "F1" >}} for help.

## Arrow Keys

Use the arrow keys to navigate:
{{< keys "Up" >}} {{< keys "Down" >}} {{< keys "Left" >}} {{< keys "Right" >}}

## Function Keys

Function keys render with compact, x-height styling:

{{< keys "F1" >}} {{< keys "F2" >}} {{< keys "F3" >}} {{< keys "F4" >}} {{< keys "F5" >}}
{{< keys "F6" >}} {{< keys "F7" >}} {{< keys "F8" >}} {{< keys "F9" >}} {{< keys "F10" >}}
{{< keys "F11" >}} {{< keys "F12" >}}

📄 02-shortcut-combos.qmd

---
title: Shortcut Combos
---

Use `shortcut=` to render multi-key combinations automatically.

## Common Editor Shortcuts

| Action | Shortcut |
|--------|----------|
| Copy | {{< keys shortcut="Ctrl+C" >}} |
| Paste | {{< keys shortcut="Ctrl+V" >}} |
| Undo | {{< keys shortcut="Ctrl+Z" >}} |
| Save | {{< keys shortcut="Ctrl+S" >}} |
| Find | {{< keys shortcut="Ctrl+F" >}} |

## VS Code Shortcuts

Open the command palette with
{{< keys shortcut="Ctrl+Shift+P" >}}.

Toggle the terminal with
{{< keys shortcut="Ctrl+Shift+`" >}}.

Quick open a file with
{{< keys shortcut="Ctrl+P" >}}.

## Manual Combos

You can also build combos manually:
{{< keys "Ctrl" >}}+{{< keys "Shift" >}}+{{< keys "P" >}}

📄 03-platform-aware.qmd

---
title: Platform-Aware Rendering
---

The `platform=` parameter translates keys for macOS or Windows.

## macOS Rendering

On macOS, modifier keys render as symbols:

| Generic | macOS |
|---------|-------|
| Ctrl | {{< keys shortcut="Ctrl+C" platform="mac" >}} |
| Cmd | {{< keys shortcut="Cmd+S" platform="mac" >}} |
| Alt/Option | {{< keys shortcut="Alt+F" platform="mac" >}} |
| Shift | {{< keys shortcut="Shift+A" platform="mac" >}} |

Command palette on macOS:
{{< keys shortcut="Cmd+Shift+P" platform="mac" >}}

## Windows Rendering

On Windows, macOS-specific keys are translated:

| macOS | Windows |
|-------|--------|
| Cmd+S | {{< keys shortcut="Cmd+S" platform="win" >}} |
| Option+F | {{< keys shortcut="Option+F" platform="win" >}} |

## Default (No Platform)

Without `platform=`, keys are rendered as-is:

{{< keys shortcut="Ctrl+Shift+P" >}}

📄 04-keys-in-context.qmd

---
title: Keys in Context
---

Keyboard shortcuts work in many documentation contexts.

## {{< keys "F1" >}} Headings with Keys

Keys can appear in section headings for quick reference.

## In Callouts

:::{.callout-tip}
## Keyboard Shortcut
Press {{< keys shortcut="Ctrl+Shift+P" >}} to open the command
palette in VS Code.
:::

:::{.callout-note}
## Navigation
Use {{< keys "Tab" >}} and {{< keys shortcut="Shift+Tab" >}} to
move between form fields.
:::

## In Lists

Common shortcuts:

- {{< keys shortcut="Ctrl+C" >}} — Copy
- {{< keys shortcut="Ctrl+V" >}} — Paste
- {{< keys shortcut="Ctrl+Z" >}} — Undo
- {{< keys shortcut="Ctrl+Y" >}} — Redo

## In Blockquotes

> Press {{< keys "Esc" >}} to close any dialog or cancel
> the current operation.

## In Prose

To save your work, press {{< keys shortcut="Ctrl+S" >}}. If you need to undo a mistake, reach for
{{< keys shortcut="Ctrl+Z" >}}. For more advanced operations,
open the command palette with {{< keys shortcut="Ctrl+Shift+P" >}}.

📄 README.md

# gdtest-keys-shortcode

A synthetic test package that exercises the `{{< keys >}}` Quarto
shortcode for rendering keyboard keys with styled key-caps.
Covers single keys, shortcut combos, platform-aware rendering,
and keys in various content contexts.

📄 great-docs.yml generated

# Great Docs Configuration
# See https://posit-dev.github.io/great-docs/user-guide/configuration.html

# Module Name (optional)
# ----------------------
# Set this if your importable module name differs from the project name.
# Example: project 'py-yaml12' with module name 'yaml12'
# module: yaml12

# Docstring Parser
# ----------------
# The docstring format used in your package (numpy, google, or sphinx)
parser: numpy

# Dynamic Introspection
# ---------------------
# Use runtime introspection for more accurate documentation (default: true)
# Set to false if your package has cyclic alias issues (e.g., PyO3/Rust bindings)
dynamic: true

# API Discovery Settings
# ----------------------
# Exclude items from auto-documentation
# exclude:
#   - InternalClass
#   - helper_function

# Logo & Favicon
# ---------------
# Point to a single logo file (replaces the text title in the navbar):
# logo: assets/logo.svg
#
# For light/dark variants:
# logo:
#   light: assets/logo-light.svg
#   dark: assets/logo-dark.svg
#
# To show the text title alongside the logo, add: show_title: true

# Funding / Copyright Holder
# --------------------------
# Credit the organization that funds or holds copyright for this package.
# Displays in sidebar and footer. Homepage and ROR provide links.
# funding:
#   name: "Posit Software, PBC"
#   roles:
#     - Copyright holder
#     - funder
#   homepage: https://posit.co
#   ror: https://ror.org/03wc8by49

# API Reference Structure
# -----------------------
# Customize the sections below to organize your API documentation.
# - Reorder items within a section to change their display order
# - Move items between sections or create new sections
# - Use 'members: false' to exclude methods from documentation
# - Add 'desc:' to sections for descriptions

reference:
  - title: Functions
    desc: Utility functions
    contents:
      - render
      - transform

# Site URL
# --------
# Canonical address of the deployed documentation site.
# Required for subdirectory deployments, skills page install commands,
# .well-known/ discovery, and sitemaps.
# site_url: "https://your-org.github.io/your-package/"

# Site Settings
# -------------
# site:
#   theme: flatly              # Quarto theme (default: flatly)
#   toc: true                  # Show table of contents (default: true)
#   toc-depth: 2               # TOC heading depth (default: 2)
#   toc-title: On this page    # TOC title (default: "On this page")

# Jupyter Kernel
# --------------
# Jupyter kernel to use for executing code cells in .qmd files.
# This is set at the project level so it applies to all pages, including
# auto-generated API reference pages. Can be overridden in individual .qmd
# file frontmatter if needed for special cases.
jupyter: python3

# CLI Documentation
# -----------------
# cli:
#   enabled: true              # Enable CLI documentation
#   module: my_package.cli     # Module containing Click commands
#   name: cli                  # Name of the Click command object