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

$3

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

``sh pnpm add @kong/markdown

`OR`

yarn add @kong/markdown`

`html

`$3`

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.

`$3`

#### v-model

- type: String- required:false- default:''

A Vue ref 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 theeditable 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:

`css .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.

`$3`

#### 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:

`html

#### 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] > Thedownloadable prop must be set to true to enable this slot.

`html v-model="content" downloadable >`

`$3`

#### 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] > Theupdate: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 of the document's YAML frontmatter.

> [!NOTE] > Theupdate: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:

`typescript 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

`sh pnpm install`

`$3`

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:

`sh pnpm run preview`

`$3`

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

`sh

`Stylelint only`


pnpm run stylelint
Stylelint and fix

pnpm run stylelint:fix
ESLint only

pnpm run lint
ESLint and fix

pnpm run lint:fix


$3
Unit and component tests are run with Vitest.

`sh

`Run tests`


pnpm run test
Run tests in the Vitest UI

pnpm run test:open

$3

`sh pnpm run build`

`$3`

![Commitizen friendly](http://commitizen.github.io/cz-cli/)

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:

`sh 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- Apre-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.

$3

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

$3

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

Kong Markdown

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

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

$3

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

``sh pnpm add @kong/markdown

`OR`

yarn add @kong/markdown`

`html

`$3`

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.

`$3`

#### v-model

- type: String- required:false- default:''

A Vue ref 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 theeditable 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.

#### 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:

`css .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.

`$3`

#### 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:

`html

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

#### 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] > Thedownloadable prop must be set to true to enable this slot.

`html v-model="content" downloadable >`

`$3`

#### 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] > Theupdate: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 of the document's YAML frontmatter.

> [!NOTE] > Theupdate: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:

`typescript 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

`sh pnpm install`

`$3`

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:

`sh pnpm run preview`

`$3`

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

`sh

`Stylelint only`


pnpm run stylelint
Stylelint and fix

pnpm run stylelint:fix
ESLint only

pnpm run lint
ESLint and fix

pnpm run lint:fix


$3
Unit and component tests are run with Vitest.

`sh

`Run tests`


pnpm run test
Run tests in the Vitest UI

pnpm run test:open

$3

`sh pnpm run build`

`$3`

![Commitizen friendly](http://commitizen.github.io/cz-cli/)

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:

`sh 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.

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

$3

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

@kong/markdown

Kong Markdown

TODO

Usage

$3

OR

$3

$3

$3

$3

Contributing & Local Development

$3

$3

Stylelint only

Stylelint and fix

ESLint only

ESLint and fix

$3

Run tests

Run tests in the Vitest UI

$3

$3

$3

$3

@kong/markdown

Kong Markdown

TODO

Usage

$3

OR

$3

$3

$3

$3

Contributing & Local Development

$3

$3

Stylelint only

Stylelint and fix

ESLint only

ESLint and fix

$3

Run tests

Run tests in the Vitest UI

$3

$3

$3

$3

Dist Tags

`OR`

`$3`

`$3`

`$3`

`$3`

`Contributing & Local Development`

`$3`

`$3`

`Stylelint only`

`Run tests`

`$3`

`OR`

`$3`

`$3`

`$3`

`$3`

`Contributing & Local Development`

`$3`

`$3`

`Stylelint only`

`Run tests`

`$3`