Kong Markdown

Kong's open-source markdown renderer and live editor.

• TODO
• Usage
  • Installation
  • Notes
  • Props
  • Slots
  • Events
• Contributing & Local Development
  • Development Sandbox
  • Lint and fix
  • Testing
  • Build for production
  • Committing Changes
  • Approvals
  • Package Publishing

TODO

Currently, the package size is... HUGE. This is due to packaging the syntax highlighter lib along with Mermaid support. In the future, this will be optimized and/or externalized.

• Optimize exports via separate bundles for syntax highlighting options

Usage

Installation

Install the @kong/markdown package in your host project.

pnpm add @kong/markdown

# OR

yarn add @kong/markdown

<template>
  <MarkdownUi
    v-model="content"
    editable
    filename="example-document"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MarkdownUi } from '@kong/markdown'
import '@kong/markdown/dist/style.css'

const content = ref<string>('# This is my markdown content')
</script>

Notes

By default, the editor does not handle the Tab key unless there is an active text selection within the textarea. This isn't an oversight —- it is an intentional decision to make the default configuration pass the "no keyboard trap" criterion of the W3C Web Content Accessibility Guidelines.

Some users browse the web without access to a pointing device, and it is really unfriendly towards such users to have focusable inputs that they cannot escape from.

Props

v-model

• type: String
• required: false
• default: ''

A Vue ref<string> from the host app that is bound to the markdown content in the host application. The value will be updated as the user edits the document and emitted via the update:modelValue event.

Alternatively, if you do not need a two-way binding, you can pass in the markdown content via the modelValue prop.

editable

• type: Boolean
• default: false

Is the user allowed to edit the document. Defaults to false.

In order to utilize the edit, split, and preview modes, this editable prop must be set to true.

Note

If the editable prop is set to false, it will override the mode and force into read-only mode.

downloadable

• type: Boolean
• default: false

Is the user allowed to download the document. Defaults to false.

filename

• type: String
• default: 'document'

The markdown document filename used when downloaded.

mode

• type: 'read' | 'edit' | 'split' | 'preview'
• required: false
• default: 'read'

The initial mode of the markdown component.

Mode	Description
read	Read-only mode. The editor is not visible. An "Edit" button is visible if the editable prop is true.
edit	Edit-only mode. The rendered markdown preview is not visible. Requires the editable prop to be set to true.
split	Split-view mode. The component is showing a side-by-side editor and markdown preview. Requires the editable prop to be set to true.
preview	Markdown preview mode. The component is showing a preview of the rendered markdown content. Requires the editable prop to be set to true.

tabSize

• type: Number
• required: false
• default: 2

The number of spaces to insert when a user tabs within the textarea. Defaults to 2 with a maximum value of 6.

theme

• type: 'light' | 'dark'
• required: false
• default: ''

The theme used when the component initializes, one of 'light' or 'dark'. Defaults to the user's browser's preferred color scheme (recommended).

To customize the colors for a specific theme, you may provide values for the underlying CSS custom properties, scoped to the container.

For example, if you want to change the rendered markdown document's background color:

.theme-light .markdown-content {
  --kui-color-background: #eee;
}
.theme-dark .markdown-content {
  --kui-color-background-inverse: #292D3E;
}

maxHeight

• type: Number
• required: false
• default: 300

The maximum height of the component when not being displayed fullscreen. Defaults to 300 with a minimum value of 100.

fullscreenOffsetTop

• type: Number
• required: false
• default: 0

When the editor is in fullscreen, the top offset, in pixels.

fullscreenZIndex

• type: Number
• required: false
• default: 1001

The z-index of the component when in fullscreen. Defaults to 1001.

Slots

editor-actions

A slot for providing editor actions to the markdown component, shown at the far-right of the toolbar.

The default slot provides Save and Cancel buttons as well as two methods, save and cancel, to trigger the built-in actions from your own component. Here's an example:

<template>
  <MarkdownUi
    v-model="content"
    editable
    @save="saveChanges"
  >
    <template #editor-actions="{ save }">
      <!-- Call the provided `save` method when custom button is clicked -->
      <button @click="save">Upload document</button>
    </template>
  </MarkdownUi>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { MarkdownUi } from '@kong/markdown'
import '@kong/markdown/dist/style.css'

const content = ref<string>('')

// When the `@save` event is emitted, POST the markdown content to the API
const saveChanges = async (markdownContent: string): Promise<void> => {
  try {
    const response = await fetch('https://example.com/documents/', {
      method: 'POST',
      headers: { 'Content-Type': 'text/markdown' },
      body: markdownContent,
    })

    const result = await response.json()
    console.log('Success:', result)
  } catch (error) {
    console.error('Error(saveChanges):', error);
  }
}
</script>

toolbar-right

A slot for providing additional toolbar content to the markdown component, shown to the right of the editor shortcuts and to the left of the editor-actions slot (the Cancel and Save buttons).

edit

A slot for providing a custom element (i.e. button) that enables the Edit mode within the component. The slot exposes the edit method to trigger the built-in function.

When the edit button (native, or custom) is clicked, the component will automatically determine whether to enable edit or split mode based on the browser's viewport width. On larger screens, the editor will launch in split mode.

content-actions

A slot for providing "floating actions" at the top right of the rendered markdown document. This slot also exposes the edit and download methods mentioned above.

download

A slot for providing a custom element (i.e. button) that triggers the Download functionality within the component. The slot exposes the download method to trigger the built-in function.

When the download button (native, or custom) is clicked, the component will download the document to the user's computer.

Note

The downloadable prop must be set to true to enable this slot.

<MarkdownUi
  v-model="content"
  downloadable
>
  <template #download="{ download }">
    <!-- Call the provided `download` method when custom button is clicked -->
    <button @click="download">Download the doc</button>
  </template>
</MarkdownUi>

Events

update:modelValue

Emitted when the user modifies the raw markdown content in the editor. The event contains a payload string of the raw markdown content.

Note

The update:modelValue event is debounced as the user is typing.

update:frontmatter

Emitted when the user modifies the raw markdown content in the editor and the internal frontmatter, if present, changes. The event contains a payload Record<string, any> of the document's YAML frontmatter.

Note

The update:frontmatter event is debounced as the user is typing.

save

Emitted whenever the user triggers the save toolbar action. The event emits a payload with the following interface:

interface EmitUpdatePayload {
  content: string
  frontmatter: Frontmatter | undefined
}

cancel

Emitted whenever the user triggers the cancel toolbar action, which also changes the component mode to read.

mode

Emitted whenever the component mode is changed. The event contains a payload string of the active mode: read | edit | split | preview

fullscreen

Emitted whenever the component is toggled in/out of fullscreen. The event contains a payload boolean indicating if fullscreen is enabled.

Contributing & Local Development

To get started, install the package dependencies

pnpm install

Development Sandbox

This repository includes a Vue sandbox app (see the /sandbox directory) to allow you to experiment with icons.

Build and Preview the Development Sandbox

To build and run a local preview of the Sandbox:

pnpm run preview

Lint and fix

Lint package files, and optionally auto-fix detected issues.

# Stylelint only
pnpm run stylelint

# Stylelint and fix
pnpm run stylelint:fix

# ESLint only
pnpm run lint

# ESLint and fix
pnpm run lint:fix

Testing

Unit and component tests are run with Vitest.

# Run tests
pnpm run test

# Run tests in the Vitest UI
pnpm run test:open

Build for production

pnpm run build

Committing Changes

This repo uses Conventional Commits.

Commitizen and Commitlint are used to help build and enforce commit messages.

It is highly recommended to use the following command in order to create your commits:

pnpm run commit

This will trigger the Commitizen interactive prompt for building your commit message.

Enforcing Commit Format

Lefthook is used to manage Git Hooks within the repo.

• A commit-msg hook is automatically setup that enforces commit message stands with commitlint, see lefthook.yaml
• A pre-push hook is used that runs eslint before allowing you to push your changes to the repository

Additionally, CI will use commitlint to validate the commits associated with a PR in the Lint and Validate job.

Approvals

• All pull requests require review and approval from authorized team members.
• Automated approvals through workflows are strictly prohibited.
  • There is an exception for automated pull request approvals originating from generated dependency updates that satisfy status checks and other requirements.
• Protected branches require at least one approval from code owners.
• All status checks must pass before a pull request may be merged.

Package Publishing

This repository utilizes Semantic Release for automated package publishing and version updates.