<mark-down> Element

An opinionated, dependency-free web vanilla js component that parses and renders markdown with extra sparkles.

This component extends standard Markdown to include YAML front matter assigned variables, wiki style links, accessibility aware images and more.

It is a little heavy (currently about 1mb, 372k gzipped), but it has a lot of "batteries included" features.

Usage

Install via npm:

npm install @lnsy/mark-down

Import the component into your project.

import "@lnsy/mark-down";

or import via cdn:

import "https://cdn.jsdelivr.net/npm/@lnsy/mark-down/dist/mark-down.min.js"

or include as a regular script tag:

<script src="https://cdn.jsdelivr.net/npm/@lnsy/mark-down/dist/mark-down.min.js"></script>

Then, use the <mark-down> custom element in your HTML.

Loading External Files

Use the src attribute to fetch and render a remote Markdown file.

<mark-down src="./path/to/your/file.md"></mark-down>

Inline Markdown

You can also place Markdown directly inside the element.

<mark-down>
  # My Document Title

  This is a paragraph with some **bold** and _italic_ text.
</mark-down>

Features

The <mark-down> element supports standard Markdown syntax with some extras.

YAML Front Matter

You can include a YAML block at the top of your Markdown to define metadata. This data is automatically parsed and attached as attributes to the <mark-down> element itself.

Example:

---
title: My Awesome Document
author: John Doe
version: 1.2.3
---

# Document Content

This document is titled "${title}" and was written by ${author}.

The title, author, and version attributes will be set on the <mark-down> element, which you can inspect in the DOM.

Slide Show

You can create a simple presentation by enabling the slide show mode. When active, the component will treat horizontal rules (---) as slide separators.

To enable it, add updated: 2025-10-30T11:09:45.897467 updated: 2025-10-30T11:11:37.643255 slide-show: true to your YAML front matter.

Example:

---
updated: 2025-10-30T11:09:45.897467
updated: 2025-10-30T11:11:37.643255
slide-show: true
title: "My Presentation"
---

# Slide 1

This is the content of the first slide.

---

# Slide 2

And this is the second slide.

This will render the content as a slideshow, with navigation controls to move between slides. All other YAML front matter attributes are still applied to the <mark-down> element as usual.

Slideshow Navigation Controls

Control the visibility and appearance of navigation buttons using attributes on the <mark-down> element.

show-controls Attribute

Add the show-controls attribute to display navigation buttons on the left and right sides of each slide. These side navigation buttons provide an alternative to the bottom navigation controls and keyboard shortcuts.

<mark-down src="presentation.md" slide-show show-controls></mark-down>

When show-controls is present or set to "true", navigation buttons will appear on the left and right edges of the slideshow. When absent or set to "false", only the bottom navigation controls will be visible.

Custom Navigation Icons

Customize the navigation button icons using Unicode symbols with the back-icon and forward-icon attributes.

<mark-down 
  src="presentation.md" 
  slide-show 
  show-controls
  back-icon="⬅"
  forward-icon="➡">
</mark-down>

Default Icons:

• back-icon: "◀" (if not specified)
• forward-icon: "▶" (if not specified)

You can use any Unicode symbol for the icons, such as arrows (←, →, ⇐, ⇒), chevrons (‹, ›), or other symbols that fit your presentation style.

Bullet Point Animations

Enable progressive reveal of list items for a more dynamic presentation experience. When enabled, bullet points appear one at a time as you navigate forward through the slide.

<mark-down 
  src="presentation.md" 
  slide-show 
  bullet-point-animations>
</mark-down>

How It Works:

When bullet-point-animations is enabled:

• Only the first list item is visible when a slide loads
• Pressing forward (arrow key, button, or click) reveals the next bullet point
• Once all bullets are visible, pressing forward advances to the next slide
• Pressing backward hides the most recently revealed bullet
• Once only the first bullet is visible, pressing backward moves to the previous slide

Example Markdown:

---
slide-show: true
---

# Key Features

- First point appears immediately
- Second point appears on next forward navigation
- Third point appears after that
- Finally, advance to next slide

---

# Next Slide

Content here...

This creates a more engaging presentation by revealing information progressively, helping maintain audience focus.

Footnotes in Slides

Footnotes are automatically positioned at the bottom of each slide when using the slideshow mode. This allows you to provide citations and additional context without cluttering the main content.

Example Markdown:

---
slide-show: true
---

# Research Findings

Our study shows significant results[^1] in the treatment group.

The control group showed minimal change[^2].

[^1]: Smith et al., 2024, Journal of Science, p. 123
[^2]: Johnson et al., 2023, Medical Review, p. 456

---

# Next Slide

More content...

Visual Appearance:

Footnotes appear at the bottom of each slide in smaller text, visually separated from the main content. Each footnote is numbered and corresponds to the reference in the slide text. Footnotes only appear on slides where they are referenced, not on every slide.

Customizing Slideshow Styles

All slideshow components use CSS classes for styling, allowing you to customize the appearance with your own stylesheets.

Available CSS Classes:

Side Navigation Controls:

• .slide-nav-side - Base class for side navigation buttons
• .slide-nav-prev - Previous button (positioned on left)
• .slide-nav-next - Next button (positioned on right)

Bullet Point Animations:

• .bullet-hidden - Applied to hidden list items
• .bullet-visible - Applied to visible list items

Footnotes:

• .slide-footnotes - Container for the footnote section
• .slide-footnotes-list - The ordered list of footnotes

Example CSS Customization:

/* Customize side navigation buttons */
.slide-nav-side {
  background-color: rgba(0, 0, 0, 0.5);
  color: white;
  font-size: 2rem;
  padding: 1rem;
  border-radius: 0.5rem;
}

.slide-nav-side:hover {
  background-color: rgba(0, 0, 0, 0.8);
}

/* Customize bullet animations */
.bullet-visible {
  animation: fadeIn 0.3s ease-in;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateX(-10px); }
  to { opacity: 1; transform: translateX(0); }
}

/* Customize footnote appearance */
.slide-footnotes {
  border-top: 2px solid #ccc;
  padding-top: 1rem;
  margin-top: 2rem;
  font-size: 0.8rem;
  color: #666;
}

These CSS classes allow you to fully customize the visual appearance of navigation controls, bullet animations, and footnotes to match your presentation style.

Variable Substitution

Variables defined in the YAML front matter can be injected directly into your Markdown content using a ${ } format.

Example:

Given the front matter:

---
username: Alex
status: active
---

This Markdown:

User **${username}** is currently **${status}**.

Will be rendered as:

User Alex is currently active.

Custom Themes

For your convenience we use css variables to adjust color and sizes.

Override these variables in your css to change how it looks:

:root {  
  --background-color: #FFF8E7;            
  --foreground-color: #5b4931;
  --neutral-bg-color: #d7d0c5;    
  --neutral-fg-color: #5e5550;        
  --highlight-color: #FE7400;     
  --secondary-color: #564c2e;     
  --trinary-color: #475569;   
  --markdown-max-width: 40rem;  
  --markdown-aside-width: 20rem;  
  --code-secondary-highlight-color: var(--secondary-color);
  --code-foreground-color: var(--fg-color);
  --code-background-color: var(--neutral-bg-color);
  --code-highlight-color: var(--trinary-color);
  --code-neutral-color: var(--neutral-fg-color);
  --h1-font-size: 2rem;
  --h2-font-size: 1.8rem;
  --h3-font-size: 1.5rem;
  --font-size: 1.0rem;
  --line-height: 1.618rem;
}

Task Lists

Create GitHub-style task lists. When a user clicks a checkbox, the component emits a checkbox-clicked custom event.

You can listen for this event to handle checkbox state changes. The event detail object contains the content of the clicked line and its lineNumber (0-indexed) in the source markdown.

Example Event Listener:

document.querySelector('mark-down').addEventListener('checkbox-clicked', (e) => {
  console.log('Checkbox clicked:', e.detail);
  // e.g., { content: '- [ ] Write documentation', lineNumber: 2 }
});

Example Markdown:

- [x] Complete initial setup
- [ ] Write documentation
- [ ] Deploy to production

renders

• [x] Complete initial setup
• [ ] Write documentation
• [ ] Deploy to production

Wiki Style Links

Create internal links using the [[Page Name]] syntax, similar to Obsidian or TiddlyWiki. This is useful for creating links to other documents within the same site.

Basic Links

By default, [[My Page]] will generate a link to /My%20Page.html.

Example:

This document links to another page: [[Getting Started]].

Aliased Links

To use different display text for a link, use a pipe | to separate the display text from the link target: [[display text|link-target]].

Example:

This is a link to [[a different page|Another Page]].

This will render a link with the text "a different page" that points to Another%20Page.html.

Customizing Link Behavior

You can customize the link behavior by setting the wikilinks-search-prefix attribute. If set, the link will become a search query instead of a direct link to an HTML file.

Example with wikilinks-search-prefix="q":

<mark-down wikilinks-search-prefix="q">
  This is a link to [[Another Page]].
</mark-down>

This will generate a link to /?q=Another%20Page. The same applies to aliased links.

Asides

Create side notes or callouts using a ::: block. This is useful for highlighting important information.

Example:

::: This is an aside. It can contain any other Markdown content, including lists, links, and code blocks. :::

:::
This is an aside. It can contain any other Markdown content, including lists, links, and code blocks.
:::

Figure with Caption

Convert embedded images in wiki-style format with a caption on the next line into a <figure> with a <figcaption>.

![[https://placehold.co/600x400/EEE/31343C]] this is alt text this is a caption

Example:

![[this-is-an-image.png]] this is alt text
this is a caption

would compile to:

<figure>
  <img src="this-is-an-image.png" alt="this is alt text">
  <figcaption>this is a caption</figcaption>
</figure>

This feature supports .jpg, .jpeg, .webp, .png, and .mp4 file endings.

Citations

Add attributions or citations using the cite: marker.

Example:

> The only thing we have to fear is fear itself.
cite: Franklin D. Roosevelt

generates

The only thing we have to fear is fear itself. cite: Franklin D. Roosevelt

Footnotes

Add footnotes to your text for citations or additional information.

Example:

Here is some text with a footnote.[^1]

[^1]: This is the footnote content.

This will render the footnote at the bottom of the document.

Here is some text with a footnote.[^5]

[^5]: This is the footnote content.

Abbreviations

Define abbreviations with their expansions, then write the short form in your text. At render time, occurrences are converted to semantic elements with a title attribute.

How to define

• Place one definition per line: *[TERM]: Expansion
• Definitions can appear anywhere (commonly near the top) and are not shown in the rendered HTML.

Example

*[HTML]: HyperText Markup Language
*[W3C]: World Wide Web Consortium

HTML is standardized by the W3C.

Renders roughly as:

<p><abbr title="HyperText Markup Language">HTML</abbr> is standardized by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

*[HTML]: HyperText Markup Language *[W3C]: World Wide Web Consortium

HTML is standardized by the W3C.

Notes

• Case-sensitive and whole-word matches.
• Expansions do not occur inside fenced code blocks or inline code spans.

Subscript and Superscript

Use subscript and superscript notation for chemistry, math, and ordinals.

• Subscript: wrap content with ~ (tilde) — example: H~2~O
• Superscript: wrap content with ^ (caret) — example: E = mc^2^

Example Markdown:

Water: H~2~O
Energy: E = mc^2^
Ordinal: 29^th^

Compiles roughly to:

<p>Water: H<sub>2</sub>O</p>
<p>Energy: E = mc<sup>2</sup></p>
<p>Ordinal: 29<sup>th</sup></p>

Water: H~2~O Energy: E = mc^2^ Ordinal: 29^th^

Notes:

• Works inline alongside other Markdown.
• Does not affect content inside code spans or fenced code blocks.

Chart Blocks

Create interactive charts using YAML configuration in fenced code blocks. Supports bar charts, scatter plots, line graphs, and donut charts via the dataroom-charts library.

Import the dataroom-chart custom elements:

  <script type="module" src="https://unpkg.com/[email protected]/dist/dataroom-charts.min.js"></script>

Example:

```chart
type: bar
width: 500
height: 300
orientation: vertical
data:
  - label: "Q1"
    value: 100
    color: "#ff6b6b"
  - label: "Q2"
    value: 150
    color: "#4ecdc4"
  - label: "Q3"
    value: 200
    color: "#45b7d1"
  - label: "Q4"
    value: 175
    color: "#96ceb4"
```

type: bar
width: 500
height: 300
orientation: vertical
monochrome: true
data:
  - label: "Q1"
    value: 100
    color: "#ff6b6b"
  - label: "Q2"
    value: 150
    color: "#4ecdc4"
  - label: "Q3"
    value: 200
    color: "#45b7d1"
  - label: "Q4"
    value: 175
    color: "#96ceb4"

This renders as an interactive <dataroom-chart> component with the specified configuration.

Supported Chart Types:

• bar or barchart - Bar charts with vertical/horizontal orientation
• scatter or scatterchart - Scatter plots with optional bubble sizing
• line, line-graph, or linegraph - Line graphs with multiple series
• donut or donutchart - Donut charts with optional labels

Common Attributes:

• type: Chart type (required)
• width, height: Dimensions in pixels
• monochrome: Enable pattern-based monochrome mode for accessibility
• color: Override default color scheme
• data: Chart data as YAML array

Network Visualizations

Create interactive network diagrams using the network code block syntax. Network visualizations support nodes, edges, and connections with attributes, allowing you to create graph-like diagrams.

Import the network-visualization cusotm html element:

  <script type="module" src="https://unpkg.com/@lnsy/[email protected]/dist/network-visualization.min.js"></script>

Basic Syntax:

```network
---
attribute: value
---

Node Name:
	Node content here (supports markdown)

Another Node:
	# Header
	Some text

---

(Node Name) --> (Another Node)
```

A network block has three sections:

1. Front Matter (optional): YAML-style attributes for the entire visualization
2. Definitions: Define nodes and edges with their content
3. Connections: Define relationships between nodes

Example with Nodes and Simple Connections:

```network

Database:
	# PostgreSQL
	Stores application data

API Server:
	# Node.js API
	Handles business logic

Frontend:
	# React App
	User interface

---

(Frontend) --> (API Server)
(API Server) --> (Database)
```

This creates a visualization with three nodes connected in sequence.

---
---
Database:
  # PostgreSQL
  Stores application data
API Server:
  # Node.js API
  Handles business logic
Frontend:
  # React App
  User interface

---
(Frontend) --> (API Server)
(API Server) --> (Database)

Code Syntax Highlighting

Code blocks are automatically highlighted using highlight.js. The language is auto-detected, but you can also specify it.

Example:

```javascript
function greet() {
  console.log("Hello, world!");
}
```

renders:

function greet() {
  console.log("Hello, world!");
}

Print Ready Style Sheets

Reasonable print style sheets for easy printing / PDF production.

Load New Markdown File By Setting src attribute

When you use setAttribute on the src attribute the component will fetch the new file and re-render the content.

<mark-down id="mark_down" src="old-file.md"></mark-down>
<script>
  mark_down.setAttribute("src", "new-file.md")
</script>

Local Development

Output Filename

You can customize the build output by creating a .env file in the root of the project.

To change the name of the output file, set the OUTPUT_FILE_NAME variable in your .env file.

.env

OUTPUT_FILE_NAME=my-custom-filename.js

If this variable is not set, the output file will default to dist/main.min.js.

Development Server Port

You can also change the development server port by setting the PORT variable in your .env file.

.env

PORT=8080

If this variable is not set, the port will default to 3000.

Running the Project

To run the project in development mode, use the following command:

npm run start

This will start a development server. By default, it runs on port 3000. You can view the project in your browser.

Building the Project

To build the project for production, use the following command:

npm run build

This will create a dist folder with the bundled and optimized files.