Repository files navigation

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

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

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

pnpm add @kong/markdown# ORyarn add @kong/markdown

<template><MarkdownUiv-model="content"editablefilename="example-document"/></template><scriptsetuplang="ts">import{ref}from'vue'import{MarkdownUi}from'@kong/markdown'import'@kong/markdown/dist/style.css'constcontent=ref<string>('# This is my markdown content')</script>

By default, the editor does not handle the Tab key unless there is an active text selection within thetextarea. 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.

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

A Vueref<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 theupdate:modelValue event.

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

• type:Boolean
• default:false

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

In order to utilize theedit,split, andpreview modes, thiseditable propmust be set totrue.

• type:Boolean
• default:false

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

• type:String
• default:'document'

The markdown document filename used when downloaded.

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

The initial mode of the markdown component.

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

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

• 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;}

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

The maximum height of the component when not being displayed fullscreen. Defaults to300 with a minimum value of100.

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

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

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

Thez-index of the component when in fullscreen. Defaults to1001.

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

The default slot providesSave andCancel buttons as well as two methods,save andcancel, to trigger the built-in actions from your own component. Here's an example:

<template><MarkdownUiv-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><scriptsetuplang="ts">import{ref}from'vue'import{MarkdownUi}from'@kong/markdown'import'@kong/markdown/dist/style.css'constcontent=ref<string>('')// When the `@save` event is emitted, POST the markdown content to the APIconstsaveChanges=async(markdownContent:string):Promise<void>=>{try{const response=awaitfetch('https://example.com/documents/',{method:'POST',headers:{'Content-Type':'text/markdown'},body:markdownContent,})constresult=awaitresponse.json()console.log('Success:',result)}catch(error){console.error('Error(saveChanges):',error);}}</script>

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

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

When theedit button (native, or custom) is clicked, the component will automatically determine whether to enableedit orsplit mode based on the browser's viewport width. On larger screens, the editor will launch insplit mode.

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

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

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

<MarkdownUiv-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>

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

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

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

interfaceEmitUpdatePayload{content:stringfrontmatter:Frontmatter|undefined}

Emitted whenever the user triggers thecancel toolbar action, which also changes the componentmode toread.

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

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

To get started, install the package dependencies

pnpm install

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

To build and run a local preview of the Sandbox:

pnpm run preview

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

# Stylelint onlypnpm run stylelint# Stylelint and fixpnpm run stylelint:fix# ESLint onlypnpm run lint# ESLint and fixpnpm run lint:fix

Unit and component tests are run withVitest.

# Run testspnpm runtest# Run tests in the Vitest UIpnpm run test:open

pnpm run build

This repo usesConventional Commits.

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

It ishighly 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.

Lefthook is used to manage Git Hooks within the repo.

• Acommit-msg hook is automatically setup that enforces commit message stands withcommitlint, seelefthook.yaml
• Apre-push hook is used that runseslint before allowing you to push your changes to the repository

Additionally, CI will usecommitlint to validate the commits associated with a PR in theLint and Validate job.

• 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.

This repository utilizesSemantic Release for automated package publishing and version updates.