@kong/markdown
Advanced tools
Kong's open-source markdown renderer and live editor.
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.
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>
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.
v-modelStringfalse''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.
editableBooleanfalseIs 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
editableprop is set tofalse, it will override themodeand force into read-only mode.
downloadableBooleanfalseIs the user allowed to download the document. Defaults to false.
filenameString'document'The markdown document filename used when downloaded.
mode'read' | 'edit' | 'split' | 'preview'false'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. |
tabSizeNumberfalse2The number of spaces to insert when a user tabs within the textarea. Defaults to 2 with a maximum value of 6.
theme'light' | 'dark'false''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;
}
maxHeightNumberfalse300The maximum height of the component when not being displayed fullscreen. Defaults to 300 with a minimum value of 100.
fullscreenOffsetTopNumberfalse0When the editor is in fullscreen, the top offset, in pixels.
fullscreenZIndexNumberfalse1001The z-index of the component when in fullscreen. Defaults to 1001.
editor-actionsA 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-rightA 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).
editA 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-actionsA 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.
downloadA 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
downloadableprop must be set totrueto 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>
update:modelValueEmitted 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:modelValueevent is debounced as the user is typing.
update:frontmatterEmitted 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:frontmatterevent is debounced as the user is typing.
saveEmitted whenever the user triggers the save toolbar action. The event emits a payload with the following interface:
interface EmitUpdatePayload {
content: string
frontmatter: Frontmatter | undefined
}
cancelEmitted whenever the user triggers the cancel toolbar action, which also changes the component mode to read.
modeEmitted whenever the component mode is changed. The event contains a payload string of the active mode: read | edit | split | preview
fullscreenEmitted whenever the component is toggled in/out of fullscreen. The event contains a payload boolean 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 only
pnpm run stylelint
# Stylelint and fix
pnpm run stylelint:fix
# ESLint only
pnpm run lint
# ESLint and fix
pnpm run lint:fix
Unit and component tests are run with Vitest.
# Run tests
pnpm run test
# Run tests in the Vitest UI
pnpm run test:open
pnpm run build
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.
Lefthook is used to manage Git Hooks within the repo.
commit-msg hook is automatically setup that enforces commit message stands with commitlint, see lefthook.yamlpre-push hook is used that runs eslint before allowing you to push your changes to the repositoryAdditionally, CI will use commitlint to validate the commits associated with a PR in the Lint and Validate job.
This repository utilizes Semantic Release for automated package publishing and version updates.
FAQs
Kong's open-source markdown renderer and live editor
The npm package @kong/markdown receives a total of 1,533 weekly downloads. As such, @kong/markdown popularity was classified as popular.
We found that @kong/markdown demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.